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: <38d102ab-d0b6-3467-4dce-4a9d4aa9e39d@gmail.com>
Date:   Mon, 16 May 2022 20:24:49 +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 v2] docs: ctucanfd: Use 'kernel-figure' directive
 instead of 'figure'
Content-Language: en-US
From:   Akira Yokosawa <akiyks@gmail.com>
To:     Marc Kleine-Budde <mkl@pengutronix.de>,
        Pavel Pisa <pisa@cmp.felk.cvut.cz>, netdev@vger.kernel.org,
        "David S. Miller" <davem@davemloft.net>,
        Jakub Kicinski <kuba@kernel.org>
Cc:     Martin Jerabek <martin.jerabek01@gmail.com>,
        Ondrej Ille <ondrej.ille@gmail.com>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
References: <05d491d4-c498-9bab-7085-9c892b636d68@gmail.com>
 <5986752a-1c2a-5d64-f91d-58b1e6decd17@gmail.com>
In-Reply-To: <5986752a-1c2a-5d64-f91d-58b1e6decd17@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

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.
>=20
> 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.
>=20
> The directive of "code:: raw" causes a warning from both
> "make htmldocs" and "make pdfdocs", which reads:
>=20
>     [...]/can/ctu/ctucanfd-driver.rst:75: WARNING: Pygments lexer name
>     'raw' is not known
>=20
> A plain literal-block marker should suffice where no syntax
> highlighting is intended.
>=20
> Fix the issues by using suitable directive and marker.
>=20
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Fixes: c3a0addefbde ("docs: ctucanfd: CTU CAN FD open-source IP core do=
cumentation.")
> 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
>=20
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(-)
>=20
> diff --git a/Documentation/networking/device_drivers/can/ctu/ctucanfd-d=
river.rst b/Documentation/networking/device_drivers/can/ctu/ctucanfd-driv=
er.rst
> index 2fde5551e756..40c92ea272af 100644
> --- a/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.r=
st
> +++ b/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver.r=
st
> @@ -72,7 +72,7 @@ it is reachable (on which bus it resides) and its con=
figuration =E2=80=93
>  registers address, interrupts and so on. An example of such a device
>  tree is given in .
> =20
> -.. code:: raw
> +::
> =20
>             / {
>                 /* ... */
> @@ -451,7 +451,7 @@ the FIFO is maintained, together with priority rota=
tion, is depicted in
> =20
>  |
> =20
> -.. figure:: fsm_txt_buffer_user.svg
> +.. kernel-figure:: fsm_txt_buffer_user.svg
> =20
>     TX Buffer states with possible transitions
> =20