| Message ID | 5986752a-1c2a-5d64-f91d-58b1e6decd17@gmail.com (mailing list archive) |
|---|---|
| State | Awaiting Upstream |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | [net-next,v2] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure' | expand |
On Wed, 11 May 2022 08:45:43 +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.") > with Sphinx versions 2.4.4 and 4.5.0. > > 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 documentation, 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.") > Acked-by: 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> > --- > Changes in v1 -> v2 > - no change in diff > - added explicit Sphinx versions the issues were observed > - picked Pavel's Acked-by > Gentle ping to netdev maintainers. I believe this one should go upstream together with the offending commit. If there is something I can do better, please let me know. Thanks, Akira > -- > .../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 >
Dear Akira, On Monday 16 of May 2022 13:24:49 Akira Yokosawa wrote: > On Wed, 11 May 2022 08:45:43 +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.") > > with Sphinx versions 2.4.4 and 4.5.0. > > > > 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 documentation, 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.") Acked-by: 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> > > --- > > Changes in v1 -> v2 > > - no change in diff > > - added explicit Sphinx versions the issues were observed > > - picked Pavel's Acked-by > > Gentle ping to netdev maintainers. > > I believe this one should go upstream together with the > offending commit. I think that the patch is on the right route thanks to Marc Kleine-Budde already, it is in the linux-can-next testing https://git.kernel.org/pub/scm/linux/kernel/git/mkl/linux-can-next.git/commit/?h=testing&id=f898bbb9c92e33dcbe7ee29b8861b707c2cd509e I hope that it would reach net-next after next linux-can-next merge. Best wishes, Pavel
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.") with Sphinx versions 2.4.4 and 4.5.0. 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 documentation, 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.") Acked-by: 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> --- Changes in v1 -> v2 - no change in diff - added explicit Sphinx versions the issues were observed - picked Pavel's Acked-by -- .../networking/device_drivers/can/ctu/ctucanfd-driver.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)