linux-kernel - [PATCH v4 14/14] docs: conf.py: properly handle include and exclude patterns

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <2238d93ac08f9e6d3e88e0edfc6f58d13f5f9b68.1749891128.git.mchehab+huawei@kernel.org>
Date: Sat, 14 Jun 2025 10:56:08 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
	Jonathan Corbet <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	"Akira Yokosawa" <akiyks@...il.com>,
	"Breno Leitao" <leitao@...ian.org>,
	"David S. Miller" <davem@...emloft.net>,
	"Donald Hunter" <donald.hunter@...il.com>,
	"Eric Dumazet" <edumazet@...gle.com>,
	"Ignacio Encinas Rubio" <ignacio@...cinas.com>,
	"Jan Stancek" <jstancek@...hat.com>,
	"Marco Elver" <elver@...gle.com>,
	"Mauro Carvalho Chehab" <mchehab+huawei@...nel.org>,
	"Paolo Abeni" <pabeni@...hat.com>,
	"Ruben Wauters" <rubenru09@....com>,
	"Shuah Khan" <skhan@...uxfoundation.org>,
	joel@...lfernandes.org,
	linux-kernel-mentees@...ts.linux.dev,
	linux-kernel@...r.kernel.org,
	lkmm@...ts.linux.dev,
	netdev@...r.kernel.org,
	peterz@...radead.org,
	stern@...land.harvard.edu
Subject: [PATCH v4 14/14] docs: conf.py: properly handle include and exclude patterns

When one does:
	make SPHINXDIRS="netlink/specs" htmldocs

the build would break because a statically-defined pattern
like:

	include_patterns = [
		...
		'netlink/specs/*.yaml',
	]

would be pointing to Documentation/netlink/specs/netlink/specs,
as the path there is relative. Also, when SPHINXDIRS is used,
the exclude_pattern = [ "output" ] is also wrong.

Fix conf.py to generate relative include/exclude patterns,
relative to the SOURCEDIR sphinx-dir parameter.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
---
 Documentation/conf.py | 58 ++++++++++++++++++++++++++++++++++---------
 1 file changed, 46 insertions(+), 12 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 62a51ac64b95..be678bdf95d4 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -17,6 +17,52 @@ 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 = ['netlink/specs/**.yaml']
+dyn_exclude_patterns = ['output']
+
+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
 # ------
 
@@ -220,18 +266,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.
-include_patterns = [
-	'**.rst',
-	'netlink/specs/*.yaml',
-]
-
-# patterns 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