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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <202205110923.24202.pisa@cmp.felk.cvut.cz>
Date:   Wed, 11 May 2022 09:23:24 +0200
From:   Pavel Pisa <pisa@....felk.cvut.cz>
To:     Akira Yokosawa <akiyks@...il.com>
Cc:     "Marc Kleine-Budde" <mkl@...gutronix.de>,
        Martin Jerabek <martin.jerabek01@...il.com>,
        Ondrej Ille <ondrej.ille@...il.com>,
        "David S. Miller" <davem@...emloft.net>,
        Jakub Kicinski <kuba@...nel.org>, netdev@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of '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
-- 
                Pavel Pisa
    phone:      +420 603531357
    e-mail:     pisa@....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@...il.com>
> >> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core
> >> documentation.") Cc: Pavel Pisa <pisa@....felk.cvut.cz>
> >> Cc: Martin Jerabek <martin.jerabek01@...il.com>
> >> Cc: Ondrej Ille <ondrej.ille@...il.com>
> >> Cc: Marc Kleine-Budde <mkl@...gutronix.de>
> >
> > Acked-by: Pavel Pisa <pisa@....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@....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