Messages in this thread | | | Date | Wed, 11 May 2022 08:34:58 +0900 | Subject | Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure' | From | Akira Yokosawa <> |
| |
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 > >
| |