Em Thu, 19 Jun 2025 11:22:19 +0900
Akira Yokosawa <akiyks@xxxxxxxxx> escreveu:
> Hi Mauro,
>
> On Mon, 16 Jun 2025 14:05:36 +0200, Mauro Carvalho Chehab wrote:
> > Em Mon, 16 Jun 2025 20:18:22 +0900
> > Akira Yokosawa <akiyks@xxxxxxxxx> escreveu:
> [...]
>
> > > I managed to reproduce the build error using debian bookworm's distro packages
> > > which can be close enough to Sphinx 5.3.0 used there.
> > >
> > > This is the error I got from "make htmldocs":
> > >
> > > ----------------------------------------------------------------
> > > Extension error (automarkup):
> > > Handler <function auto_markup at 0x796307745bc0> for event 'doctree-resolved' threw an exception (exception: argument for warn() given by name ('stacklevel') and position (3))
> > > ----------------------------------------------------------------
>
> > Perhaps it is related to docutils version.
>
> Looks like you are right.
>
> debian:12 (Sphinx 5.3.0) and mageia:9 (Sphinx 6.1.3) are distro releases
> whose docutils is 0.19. They both show the same symptom.
>
> Furthermore, if I install Sphinx by using venv and saying:
>
> pip install "docutils==0.19" Sphinx pyyaml
>
> , I have Sphinx 7.3.6 and it shows the same symptom.
>
> So you need to say "docutils!=0.19" when you install specific versions
> of Sphinx.
>
> >
> > Assuming that it doesn't work with certain versions of sphinx or
> > docutils, instead of reverting the entire patch, IMO the best would
> > be to add a check for Sphinx version, disabling the broken refs
> > only for too old versions.
> >
>
> Can you do so against docutils 0.19 only?
If we're willing to do that, IMO we need to do a more generic solution
that will compare both versions and warn if incompatibilities are
detected.
Something like the enclosed patch (it is against my latest conf.py
patch).
Thanks,
Mauro
---
[PATCH] docs: conf.py: Check Sphinx and docutils version
As reported by Akira, there are incompatibility issues with
Sphinx and docutils.
I manually checked that before docutils 0.17.1, yaml generation
doesn't work properly. Akira checked that 0.19 is problematic too.
After check Sphinx release notes, it seems that the
versions that are supposed to cope well together are:
======== ============ ============
Sphinx Min Docutils Max Docutils
Version Version Version
-------- ------------ ------------
< 4.0.0 0.17.1 0.17.1
< 6.0.0 0.17.1 0.18.1
< 7.0.0 0.18.0 0.18.1
>= 7.0.0 0.20.0 0.21.2
======== ============ ============
Add a logic inside conf.py to check the above, emitting warnings
if the docutils version don't match what is known to be supported.
Reported-by: Akira Yokosawa <akiyks@xxxxxxxxx>
Closes: https://lore.kernel.org/linux-doc/6fcb75ee-61db-4fb3-9c5f-2029a7fea4ee@xxxxxxxxx/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 5eddf5885f77..6047ec85add1 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -9,7 +9,11 @@ import os
import shutil
import sys
+import docutils
import sphinx
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@@ -21,11 +25,34 @@ from load_config import loadConfig # pylint: disable=C0413,E0401
# Minimal supported version
needs_sphinx = "3.4.3"
-# Get Sphinx version
-major, minor, patch = sphinx.version_info[:3] # pylint: disable=I1101
+# Get Sphinx and docutils versions
+sphinx_ver = sphinx.version_info[:3] # pylint: disable=I1101
+docutils_ver = docutils.__version_info__[:3]
+
+#
+if sphinx_ver < (4, 0, 0):
+ min_docutils = (0, 16, 0)
+ max_docutils = (0, 17, 1)
+elif sphinx_ver < (6, 0, 0):
+ min_docutils = (0, 17, 0)
+ max_docutils = (0, 18, 1)
+elif sphinx_ver < (7, 0, 0):
+ min_docutils = (0, 18, 0)
+ max_docutils = (0, 18, 1)
+else:
+ min_docutils = (0, 20, 0)
+ max_docutils = (0, 21, 2)
+
+sphinx_ver_str = ".".join([str(x) for x in sphinx_ver])
+docutils_ver_str = ".".join([str(x) for x in docutils_ver])
+
+if docutils_ver < min_docutils:
+ logger.warning(f"Docutils {docutils_ver_str} is too old for Sphinx {sphinx_ver_str}. Doc generation may fail")
+elif docutils_ver > max_docutils:
+ logger.warning(f"Docutils {docutils_ver_str} could be too new for Sphinx {sphinx_ver_str}. Doc generation may fail")
# Include_patterns were added on Sphinx 5.1
-if (major < 5) or (major == 5 and minor < 1):
+if sphinx_ver < (5, 1, 0):
has_include_patterns = False
else:
has_include_patterns = True
