Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <268372a9-2f6a-74f3-29ea-c51536a73dba@gmail.com>
Date:   Wed, 11 May 2022 08:34:58 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.8.1
Subject: Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive
 instead of 'figure'
Content-Language: en-US
To:     Pavel Pisa <pisa@cmp.felk.cvut.cz>
Cc:     Marc Kleine-Budde <mkl@pengutronix.de>,
        Martin Jerabek <martin.jerabek01@gmail.com>,
        Ondrej Ille <ondrej.ille@gmail.com>,
        "David S. Miller" <davem@davemloft.net>,
        Jakub Kicinski <kuba@kernel.org>, netdev@vger.kernel.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
References: <05d491d4-c498-9bab-7085-9c892b636d68@gmail.com>
 <202205101825.15126.pisa@cmp.felk.cvut.cz>
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <202205101825.15126.pisa@cmp.felk.cvut.cz>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

On Tue, 10 May 2022 18:25:15 +0200,
Pavel Pisa wrote:
> Hello Akira,
>=20
> 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.").
>=20
> Thanks for the fix
>=20
>> The plain "figure" directive broke "make pdfdocs" due to a missing=20
>> PDF figure.  For conversion of SVG -> PDF to work, the "kernel-figure"=

>> directive, which is an extension for kernel documentations, should
>> be used instead.
>=20
> 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..=
=2E
>=20
> https://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/doc/linux_driver/buil=
d/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

>=20
>> 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
>=20
> 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

>=20
> Anyway thanks for cleanup.
>=20
>> 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>
>=20
> Acked-by: Pavel Pisa <pisa@cmp.felk.cvut.cz>
>=20
>> ---
>>  .../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 =E2=80=93 registers address, interrupts and so on. An ex=
ample 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
>=20
>=20