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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Hi Akira,

Em Sun, 22 Jun 2025 20:19:52 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

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

True, but the same also happened with me at the parser_yaml code.

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

That's not the best solution. 

See, Docutils 0.17 was released in Jun, 2021. and 0.17.1 on
October, 2021. If we look at the Sphinx releases, we have:

======  ===================
Sphinx  Release Date
------  -------------------
4.1.0	June 10, 2021
4.1.1	July 25, 2021
4.1.2	August 1, 2021
4.1.3	August 15, 2021
4.2.0	September 28, 2021
======  ===================

As Sphinx policy is to not even fix bugs when a new release
happens, it means that, at the best, the minimal version made to be
compatible with 0.17 is 4.1.x, and the minimal compatible with
0.17.1 is 4.2.x.

So, if we want not to raise the minimal version to 4.2.x (*), the right 
fix is this (I'll be sending at the upcoming YAML patch series I'll be
sending next week):

diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
index 8288e2ff7c7c..1602b31f448e 100755
--- a/Documentation/sphinx/parser_yaml.py
+++ b/Documentation/sphinx/parser_yaml.py
@@ -77,6 +77,10 @@ class YamlParser(Parser):
 
                 result.append(line, document.current_source, lineoffset)
 
+            # Fix backward compatibility with docutils < 0.17.1
+            if "tab_width" not in vars(document.settings):
+                document.settings.tab_width = 8
+
             rst_parser = RSTParser()
             rst_parser.parse('\n'.join(result), document)

What happens is that Sphinx is a shell case built on the top of
docutils: the actual ReST parser is inside docutils. 

(*) the exact patch where 0.17.1 support was added/tested on
    Sphinx needs to be checked

Now, there is another alternative: raise the bar, increasing minimal
versions for Python and Sphinx. Yet, I would do it only once per year.

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

Heh, playing with scripts/test_doc_build.py, pip allowed to create
several environments that are valid for the package management software
but either:

- cause sphinx-build to crash even before returning Sphinx version;
- crash in the middle of the compilation.

As I said, Sphinx is a shell on the top of docutils. Some of the code
there seem to depend on subtile behaviors, like the one with
the tab_width affecting parser_yaml.py on certain Sphinx/docutils
combinations or the one fixed by Jon with regards to setup a class
for the broken references.

The idea of this patch is to warn the one building the docs
that he might be navigating turbulent waters when it is unknown
if the combination is supported. It also better defines the
scope of backward compatibility we want to provide.

Thanks,
Mauro