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 <[email protected]>
Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core documentation.")
Cc: Pavel Pisa <[email protected]>
Cc: Martin Jerabek <[email protected]>
Cc: Ondrej Ille <[email protected]>
Cc: Marc Kleine-Budde <[email protected]>
---
.../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
--
2.25.1
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 <[email protected]>
Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core documentation.")
Acked-by: Pavel Pisa <[email protected]>
Cc: Martin Jerabek <[email protected]>
Cc: Ondrej Ille <[email protected]>
Cc: Marc Kleine-Budde <[email protected]>
---
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(-)
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
--
2.25.1
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
--
An old man doll... just what I always wanted! - Clara
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
--
Pavel Pisa
phone: +420 603531357
e-mail: [email protected]
Department of Control Engineering FEE CVUT
Karlovo namesti 13, 121 35, Prague 2
university: http://control.fel.cvut.cz/
personal: http://cmp.felk.cvut.cz/~pisa
projects: https://www.openhub.net/accounts/ppisa
CAN related:http://canbus.pages.fel.cvut.cz/
Open Technologies Research Education and Exchange Services
https://gitlab.fel.cvut.cz/otrees/org/-/wikis/home
> 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 <[email protected]>
> >> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core
> >> documentation.") Cc: Pavel Pisa <[email protected]>
> >> Cc: Martin Jerabek <[email protected]>
> >> Cc: Ondrej Ille <[email protected]>
> >> Cc: Marc Kleine-Budde <[email protected]>
> >
> > Acked-by: Pavel Pisa <[email protected]>
> >
> >> ---
> >> .../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
--
Yours sincerely
Pavel Pisa
phone: +420 603531357
e-mail: [email protected]
Department of Control Engineering FEE CVUT
Karlovo namesti 13, 121 35, Prague 2
university: http://control.fel.cvut.cz/
personal: http://cmp.felk.cvut.cz/~pisa
projects: https://www.openhub.net/accounts/ppisa
CAN related:http://canbus.pages.fel.cvut.cz/
Open Technologies Research Education and Exchange Services
https://gitlab.fel.cvut.cz/otrees/org/-/wikis/home
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 <[email protected]>
> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core
> documentation.") Cc: Pavel Pisa <[email protected]>
> Cc: Martin Jerabek <[email protected]>
> Cc: Ondrej Ille <[email protected]>
> Cc: Marc Kleine-Budde <[email protected]>
Acked-by: Pavel Pisa <[email protected]>
> ---
> .../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 <[email protected]>
>> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core
>> documentation.") Cc: Pavel Pisa <[email protected]>
>> Cc: Martin Jerabek <[email protected]>
>> Cc: Ondrej Ille <[email protected]>
>> Cc: Marc Kleine-Budde <[email protected]>
>
> Acked-by: Pavel Pisa <[email protected]>
>
>> ---
>> .../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 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
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 <[email protected]>
> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core documentation.")
> Acked-by: Pavel Pisa <[email protected]>
> Cc: Martin Jerabek <[email protected]>
> Cc: Ondrej Ille <[email protected]>
> Cc: Marc Kleine-Budde <[email protected]>
> ---
> 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 <[email protected]>
> > Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core
> > documentation.") Acked-by: Pavel Pisa <[email protected]>
> > Cc: Martin Jerabek <[email protected]>
> > Cc: Ondrej Ille <[email protected]>
> > Cc: Marc Kleine-Budde <[email protected]>
> > ---
> > 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
--
Pavel Pisa
phone: +420 603531357
e-mail: [email protected]
Department of Control Engineering FEE CVUT
Karlovo namesti 13, 121 35, Prague 2
university: http://control.fel.cvut.cz/
personal: http://cmp.felk.cvut.cz/~pisa
projects: https://www.openhub.net/accounts/ppisa
CAN related:http://canbus.pages.fel.cvut.cz/
Open Technologies Research Education and Exchange Services
https://gitlab.fel.cvut.cz/otrees/org/-/wikis/home