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