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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <268372a9-2f6a-74f3-29ea-c51536a73dba@gmail.com>
Date:   Wed, 11 May 2022 08:34:58 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Pavel Pisa <pisa@....felk.cvut.cz>
Cc:     Marc Kleine-Budde <mkl@...gutronix.de>,
        Martin Jerabek <martin.jerabek01@...il.com>,
        Ondrej Ille <ondrej.ille@...il.com>,
        "David S. Miller" <davem@...emloft.net>,
        Jakub Kicinski <kuba@...nel.org>, netdev@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive
 instead of 'figure'

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@...il.com>
>> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core
>> documentation.") Cc: Pavel Pisa <pisa@....felk.cvut.cz>
>> Cc: Martin Jerabek <martin.jerabek01@...il.com>
>> Cc: Ondrej Ille <ondrej.ille@...il.com>
>> Cc: Marc Kleine-Budde <mkl@...gutronix.de>
> 
> Acked-by: Pavel Pisa <pisa@....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
> 
>