Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Akira Yokosawa <akiyks@gmail.com>]

On Tue, 10 May 2022 18:25:15 +0200,
Pavel Pisa wrote:
> Hello Akira,
> 
> On Tuesday 10 of May 2022 11:34:37 Akira Yokosawa wrote:
>> Two issues were observed in the ReST doc added by commit c3a0addefbde
>> ("docs: ctucanfd: CTU CAN FD open-source IP core documentation.").
> 
> Thanks for the fix
> 
>> The plain "figure" directive broke "make pdfdocs" due to a missing 
>> PDF figure.  For conversion of SVG -> PDF to work, the "kernel-figure"
>> directive, which is an extension for kernel documentations, should
>> be used instead.
> 
> I have not noticed that there is kernel-figure
> option. We have setup own Sphinx 1.4.9 based build for driver
> documentation out of the tree compilation, I am not sure if that
> would work with this option but if not we keep this version
> modified. There are required modification for sources location anyway...
> 
> https://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/doc/linux_driver/build/ctucanfd-driver.html

You might want to see kernel's doc-guide at

    https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html

, or its source

    Documentation/doc-guide/sphinx.rst

> 
>> The directive of "code:: raw" causes a warning from both
>> "make htmldocs" and "make pdfdocs", which reads:
>>
>>     [...]/can/ctu/ctucanfd-driver.rst:75: WARNING: Pygments lexer name
>>     'raw' is not known
> 
> Strange I have not seen any warning when building htmldocs
> in my actual linux kernel tree. I have cleaned docs to be warnings
> free, but it is possible that I have another tools versions.
Well, I don't think "make htmldocs" runs with Sphinx 1.4.9.

You mean 1.7.9?

Then the above mentioned warning is not shown.
I see the warning with Sphinx versions 2.4.4. and 4.5.0.

I'll amend the changelog to mention the Sphinx versions and
post as v2.

        Thanks, Akira

> 
> Anyway thanks for cleanup.
> 
>> A plain literal-block marker should suffice where no syntax
>> highlighting is intended.
>>
>> Fix the issues by using suitable directive and marker.
>>
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core
>> documentation.") Cc: Pavel Pisa <pisa@cmp.felk.cvut.cz>
>> Cc: Martin Jerabek <martin.jerabek01@gmail.com>
>> Cc: Ondrej Ille <ondrej.ille@gmail.com>
>> Cc: Marc Kleine-Budde <mkl@pengutronix.de>
> 
> Acked-by: Pavel Pisa <pisa@cmp.felk.cvut.cz>
> 
>> ---
>>  .../networking/device_drivers/can/ctu/ctucanfd-driver.rst     | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git
>> a/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst
>> b/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst index
>> 2fde5551e756..40c92ea272af 100644
>> --- a/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst
>> +++ b/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.rst
>> @@ -72,7 +72,7 @@ it is reachable (on which bus it resides) and its
>> configuration – registers address, interrupts and so on. An example of such
>> a device tree is given in .
>>
>> -.. code:: raw
>> +::
>>
>>             / {
>>                 /* ... */
>> @@ -451,7 +451,7 @@ the FIFO is maintained, together with priority
>> rotation, is depicted in
>>
>>
>>
>> -.. figure:: fsm_txt_buffer_user.svg
>> +.. kernel-figure:: fsm_txt_buffer_user.svg
>>
>>     TX Buffer states with possible transitions
> 
>