lkml.org 
[lkml]   [2022]   [May]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'
From
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
>
>

\
 
 \ /
  Last update: 2022-05-11 01:35    [W:0.104 / U:0.224 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site