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@xxxxxxxxxx>
> Reviewed-by: Donald Hunter <donald.hunter@xxxxxxxxx>
> ---
> 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
