Hi Akira,

Em Sun, 22 Jun 2025 20:19:52 +0900
Akira Yokosawa [off-list ref] escreveu:

On Sun, 22 Jun 2025 08:02:44 +0200, Mauro Carvalho Chehab wrote:

quoted

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