Re: [PATCH v3 15/15] docs: conf.py: Check Sphinx and docutils version

[Akira Yokosawa <akiyks@gmail.com>]

On Sun, 22 Jun 2025 08:02:44 +0200, Mauro Carvalho Chehab wrote:
> As reported by Akira, there were incompatibility issues with
> Sphinx and docutils with docutils 0.19. There's already
> a fix for it, but, as there are incompatibility issues with
> different versions, better to add a check to verify if the
> combination is supported/tested.
> 

I've been skeptical of adding such checks in conf.py.

What happened the other day was that Jon used a deprecated (and rarely
used) method of docutils which failed to work properly only in
docutils 0.19 (there is no mention of related issues in its and 
nearby release notes).

Your integration of parser_yaml extension will raise the minimum
version of docutils to 0.17.1.  I think all you will need is just
to check:

    docutils < 0.17.1

, and to make a warning regardless of Sphinx versions.

> After check Sphinx release notes, it seems that the
> version compatibility is given by:
> 
>         =======  ============   ============
>         Sphinx   Min Docutils   Max Docutils
>         Version  Version        Version
>         -------  ------------   ------------
>         3.4.3    >= 0.12.0      < 0.18.0
>         4.0.0    >= 0.12.0      < 0.19.0
>         6.0.0    >= 0.18.0      < 0.20.0
>         7.0.0    >= 0.18.1      < 0.21.0
>         7.2.0    >= 0.18.1      < 0.20.0
>         7.4.0    >= 0.18.1      < 0.21.0
>         8.0.0    >= 0.20.0      < 0.22.0
>         8.2.3    >= 0.20.0      < 0.22.0
>         =======  ============   ============
> 

<nitpick>

So this is what I see in the changelog (not looked into < 6.0.0):

         ================= ====================
          Sphinx version     docutils version
          (since)              min       max
         ----------------- ------------ -------
         6.0.0             >= 0.18      < 0.20
         6.2.0             >= 0.18.1    < 0.20
	 7.0.1             >= 0.18.1    < 0.21
         7.3.0             >= 0.18.1    < 0.22
	 7.4.0             >= 0.20      < 0.22
	 (up to 8.2.3)
         ================= ====================

This Looks quite different from yours ...

</nitpick>

That said, these dependencies should be recognized and taken care of by
pip/PyPI (or whatever distro package management system), and already met;
unless you have done something strange/dangerous and screwed up your Sphinx
installation.

My limited imagination prevents me from coming up with any plausible
scenario where these checks at every sphinx-build invocation can be helpful.

> For now, add a logic inside conf.py to check the above
> compatibility list, emitting warnings if the docutils
> version doesn't match it.
> 
> This way, when we discover incompatibility issues, we
> can easily adjust the table.

Does not sound convincing enough to me.  Sorry.

        Thanks, Akira

>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/conf.py | 70 +++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 67 insertions(+), 3 deletions(-)
[...]