[PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Akira Yokosawa]

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(-)

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

Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Pavel Pisa]

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

Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[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
> 
> 

Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Pavel Pisa]

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:     pisa@cmp.felk.cvut.cz
    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 <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


-- 
Yours sincerely

                Pavel Pisa
    phone:      +420 603531357
    e-mail:     pisa@cmp.felk.cvut.cz
    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

[PATCH net-next v2] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Akira Yokosawa]

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(-)

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

Re: [PATCH net-next v2] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Akira Yokosawa]

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
>  

Re: [PATCH net-next v2] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Pavel Pisa]

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
-- 
                Pavel Pisa
    phone:      +420 603531357
    e-mail:     pisa@cmp.felk.cvut.cz
    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

Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Bagas Sanjaya]

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

Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

[Akira Yokosawa]

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