[PATCH v7 17/17] docs: conf.py: Check Sphinx and docutils version

Mauro Carvalho Chehab
2025-06-19T06:50:21Z

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@gmail.com>
Closes: https://lore.kernel.org/linux-doc/6fcb75ee-61db-4fb3-9c5f-2029a7fea4ee@gmail.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 33 ++++++++++++++++++++++++++++++---
1 file changed, 30 insertions(+), 3 deletions(-)

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