Re: [PATCH v6 01/15] docs: conf.py: properly handle include and exclude patterns

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed, 18 Jun 2025 08:42:51 -0700
Breno Leitao <leitao@debian.org> escreveu:

> On Wed, Jun 18, 2025 at 01:46:28PM +0200, Mauro Carvalho Chehab wrote:
> > When one does:
> > 	make SPHINXDIRS="foo" htmldocs
> > 
> > All patterns would be relative to Documentation/foo, which
> > causes the include/exclude patterns like:
> > 
> > 	include_patterns = [
> > 		...
> > 		f'foo/*.{ext}',
> > 	]
> > 
> > to break. This is not what it is expected. Address it by
> > adding a logic to dynamically adjust the pattern when
> > SPHINXDIRS is used.
> > 
> > That allows adding parsers for other file types.
> > 
> > It should be noticed that include_patterns was added on
> > Sphinx 5.1:
> > 	https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-include_patterns
> > 
> > So, a backward-compatible code is needed when we start
> > using it for real.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > Reviewed-by: Donald Hunter <donald.hunter@gmail.com>
> > ---
> >  Documentation/conf.py | 67 ++++++++++++++++++++++++++++++++++++++++---
> >  1 file changed, 63 insertions(+), 4 deletions(-)
> > 
> > diff --git a/Documentation/conf.py b/Documentation/conf.py
> > index 12de52a2b17e..4ba4ee45e599 100644
> > --- a/Documentation/conf.py
> > +++ b/Documentation/conf.py
> > @@ -17,6 +17,66 @@ import os
> >  import sphinx
> >  import shutil
> >  
> > +# Get Sphinx version
> > +major, minor, patch = sphinx.version_info[:3]
> > +
> > +# Include_patterns were added on Sphinx 5.1
> > +if (major < 5) or (major == 5 and minor < 1):
> > +    has_include_patterns = False
> > +else:
> > +    has_include_patterns = True
> > +    # Include patterns that don't contain directory names, in glob format
> > +    include_patterns = ['**.rst']
> > +
> > +# Location of Documentation/ directory
> > +doctree = os.path.abspath('.')
> > +
> > +# Exclude of patterns that don't contain directory names, in glob format.
> > +exclude_patterns = []
> > +
> > +# List of patterns that contain directory names in glob format.
> > +dyn_include_patterns = []
> > +dyn_exclude_patterns = ['output']
> > +
> > +# Properly handle include/exclude patterns
> > +# ----------------------------------------
> > +
> > +def update_patterns(app):
> > +  
> 
> PEP-257 says we don't want a line before docstring:
> 
> https://peps.python.org/pep-0257/#multi-line-docstrings

True, but:

$ pylint Documentation/conf.py 
************* Module conf
Documentation/conf.py:357:0: W0311: Bad indentation. Found 16 spaces, expected 12 (bad-indentation)
Documentation/conf.py:587:0: W0311: Bad indentation. Found 1 spaces, expected 4 (bad-indentation)
Documentation/conf.py:567:1: W0511: FIXME: Do not add the index file here; the result will be too big. Adding (fixme)
Documentation/conf.py:1:0: C0114: Missing module docstring (missing-module-docstring)
Documentation/conf.py:229:0: W0622: Redefining built-in 'copyright' (redefined-builtin)
Documentation/conf.py:21:22: I1101: Module 'sphinx' has no 'version_info' member, but source is unavailable. Consider adding this module to extension-pkg-allow-list if you want to perform analysis based on run-time introspection of living objects. (c-extension-no-member)
Documentation/conf.py:25:4: C0103: Constant name "has_include_patterns" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:27:4: C0103: Constant name "has_include_patterns" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:65:4: W0612: Unused variable 'sourcedir' (unused-variable)
Documentation/conf.py:66:4: W0612: Unused variable 'builddir' (unused-variable)
Documentation/conf.py:104:0: E0401: Unable to import 'load_config' (import-error)
Documentation/conf.py:104:0: C0413: Import "from load_config import loadConfig" should be placed at the top of the module (wrong-import-position)
Documentation/conf.py:109:0: C0103: Constant name "needs_sphinx" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:186:0: C0103: Constant name "autosectionlabel_prefix_document" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:187:0: C0103: Constant name "autosectionlabel_maxdepth" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:200:8: C0103: Constant name "load_imgmath" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:202:8: C0103: Constant name "load_imgmath" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:204:25: C0209: Formatting a regular string which could be an f-string (consider-using-f-string)
Documentation/conf.py:208:4: C0103: Constant name "math_renderer" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:210:4: C0103: Constant name "math_renderer" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:225:0: C0103: Constant name "master_doc" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:228:0: C0103: Constant name "project" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:229:0: C0103: Constant name "copyright" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:230:0: C0103: Constant name "author" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:253:0: W0702: No exception type(s) specified (bare-except)
Documentation/conf.py:243:4: C0103: Constant name "makefile_version" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:244:4: C0103: Constant name "makefile_patchlevel" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:245:16: R1732: Consider using 'with' for resource-allocating operations (consider-using-with)
Documentation/conf.py:245:16: W1514: Using open without explicitly specifying an encoding (unspecified-encoding)
Documentation/conf.py:259:8: C0103: Constant name "version" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:259:18: C0103: Constant name "release" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:266:0: C0116: Missing function or method docstring (missing-function-docstring)
Documentation/conf.py:284:0: C0103: Constant name "language" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:308:0: C0103: Constant name "pygments_style" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:317:0: C0103: Constant name "todo_include_todos" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:319:0: C0103: Constant name "primary_domain" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:320:0: C0103: Constant name "highlight_language" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:328:0: C0103: Constant name "html_theme" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:334:3: R1714: Consider merging these comparisons with 'in' by using 'html_theme in ('sphinx_rtd_theme', 'sphinx_rtd_dark_mode')'. Use a set instead if elements are hashable. (consider-using-in)
Documentation/conf.py:353:16: W0104: Statement seems to have no effect (pointless-statement)
Documentation/conf.py:364:8: C0103: Constant name "html_theme" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:382:17: C0209: Formatting a regular string which could be an f-string (consider-using-f-string)
Documentation/conf.py:392:0: C0103: Constant name "smartquotes_action" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:404:0: C0103: Constant name "html_logo" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:407:0: C0103: Constant name "htmlhelp_basename" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:487:8: C0103: Constant name "has" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:490:16: C0103: Constant name "has" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:494:36: C0209: Formatting a regular string which could be an f-string (consider-using-f-string)
Documentation/conf.py:551:0: C0103: Constant name "epub_title" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:552:0: C0103: Constant name "epub_author" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:553:0: C0103: Constant name "epub_publisher" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:554:0: C0103: Constant name "epub_copyright" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:571:29: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
Documentation/conf.py:571:40: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
Documentation/conf.py:571:51: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
Documentation/conf.py:577:0: C0103: Constant name "kerneldoc_bin" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:578:0: C0103: Constant name "kerneldoc_srctree" doesn't conform to UPPER_CASE naming style (invalid-name)
Documentation/conf.py:586:0: C0116: Missing function or method docstring (missing-function-docstring)
Documentation/conf.py:18:0: C0411: standard import "shutil" should be placed before third party import "sphinx" (wrong-import-order)
Documentation/conf.py:350:16: W0611: Unused import sphinx_rtd_dark_mode (unused-import)

This file needs a major cleanup, as it is currently not following
any Python code style, and still has some Phython 2.x legacy
coding styles.

Perhaps it is time to take some care of it and on other
sphinx/*.py files that aren't compliant ;-)

Thanks,
Mauro