Re: [PATCH v6 01/15] docs: conf.py: properly handle include and exclude patterns
From: Breno Leitao <leitao@debian.org>
Date: 2025-06-18 15:42:56
Also in:
linux-doc, linux-kernel-mentees, lkml
On Wed, Jun 18, 2025 at 01:46:28PM +0200, Mauro Carvalho Chehab wrote:
quoted hunk ↗ jump to hunk
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