[PATCH v5 01/15] docs: conf.py: properly handle include and exclude patterns
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2025-06-17 08:02:32
Also in:
linux-doc, linux-kernel-mentees, lkml
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 52 +++++++++++++++++++++++++++++++++++++++----
1 file changed, 48 insertions(+), 4 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 12de52a2b17e..e887c1b786a4 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py@@ -17,6 +17,54 @@ import os import sphinx import shutil +# Location of Documentation/ directory +doctree = os.path.abspath('.') + +# List of patterns that don't contain directory names, in glob format. +include_patterns = ['**.rst'] +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 setup(app): + """ + On Sphinx, all directories are relative to what it is passed as + SOURCEDIR parameter for sphinx-build. Due to that, all patterns + that have directory names on it need to be dynamically set, after + converting them to a relative patch. + + As Sphinx doesn't include any patterns outside SOURCEDIR, we should + exclude relative patterns that start with "../". + """ + + sourcedir = app.srcdir # full path to the source directory + builddir = os.environ.get("BUILDDIR") + + # setup include_patterns dynamically + for p in dyn_include_patterns: + full = os.path.join(doctree, p) + + rel_path = os.path.relpath(full, start = app.srcdir) + if rel_path.startswith("../"): + continue + + app.config.include_patterns.append(rel_path) + + # setup exclude_patterns dynamically + for p in dyn_exclude_patterns: + full = os.path.join(doctree, p) + + rel_path = os.path.relpath(full, start = app.srcdir) + if rel_path.startswith("../"): + continue + + app.config.exclude_patterns.append(rel_path) + # helper # ------
@@ -219,10 +267,6 @@ language = 'en' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['output'] - # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None
--
2.49.0