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