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

[Breno Leitao <leitao@debian.org>]

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