Re: Error at www.kernel.org/doc/html/next/ since next-20250610

[Randy Dunlap <rdunlap@infradead.org>]

On 6/18/25 11:16 PM, Mauro Carvalho Chehab wrote:
> Em Thu, 19 Jun 2025 11:22:19 +0900
> Akira Yokosawa <akiyks@gmail.com> 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@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>
> 
> 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