| Message ID | 05d491d4-c498-9bab-7085-9c892b636d68@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | [net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure' | expand |
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 > 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. 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
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 > >
On Tue, May 10, 2022 at 06:34:37PM +0900, 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."). > > 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. > Does plain "figure" directive not currently support SVG file argument? Because when I see reST documentation ([1]), it doesn't explicitly mentioned supported image formats. [1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure
Hello Akira, On Wednesday 11 of May 2022 01:34:58 Akira Yokosawa wrote: > On Tue, 10 May 2022 18:25:15 +0200, > > Pavel Pisa wrote: > > Hello Akira, ... > > 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 I think I have read it in 2019 when I have managed to switch to kernel format documentation in out of the tree driver build https://gitlab.fel.cvut.cz/canbus/ctucanfd_ip_core/-/commit/09983d11ab34977104d2be0b1376d4c93d9a01cb Then I have enhanced documentation text and picture from Martin Jerabek's thesis etc.. > >> 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. This is Sphinx version reported by out of tree documentation build. It can be hidden in one of dockers which are used by gitlabrunner for CI. When I find some time I can look for update. > You mean 1.7.9? My local net-next make htmldocs generated pages report Sphinx version 1.8.4. So this seems to be a mix, but I agree that it is important to clean docs in the state when it works for each not totally archaic setup. Thanks for the feedback, Pavel
On Wed, 11 May 2022 13:37:31 +0700, Bagas Sanjaya wrote: > On Tue, May 10, 2022 at 06:34:37PM +0900, 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."). >> >> 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. >> > > Does plain "figure" directive not currently support SVG file argument? > Because when I see reST documentation ([1]), it doesn't explicitly > mentioned supported image formats. > > [1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure > Close! See: https://docutils.sourceforge.io/docs/ref/rst/directives.html#images There you see the compatibility table of image format vs output format/user agent. The argument (URI) can be in any format a consumer of generated document can render. It's user's (read: kernel-documentation tool's) responsibility to prepare images in suitable formats. For kernel documentation, the "kernel-figure" directive triggers the conversion of images depending on the output format, so that compatible images can be used in the generated documents. Those conversions are independent of what you write in .rst files. If there emerges another output target which prefers a different image format, you can always modify the extension code in kfigure.py. Thanks, Akira
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
Two issues were observed in the ReST doc added by commit c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core documentation."). 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. 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 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> --- .../networking/device_drivers/can/ctu/ctucanfd-driver.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)