On 6/18/25 11:16 PM, Mauro Carvalho Chehab wrote: > Em Thu, 19 Jun 2025 11:22:19 +0900 > Akira Yokosawa <akiyks@xxxxxxxxx> escreveu: > >> >> 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]) That ".". (2 times) is ugly. ;) (needs spaces added IMO) Is that compliant with PEP8? I can't see that PEP8 addresses usage of . directly. For some binary operators: Always surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <=, >=, in, not in, is, is not), Booleans (and, or, not). [https://peps.python.org/pep-0008/#whitespace-in-expressions-and-statements] Thanks. > + > +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 > > -- ~Randy
