[PATCH 5/9] docs: maintainers_include.py: clean most SPHINXDIRS=process warnings

Mauro Carvalho Chehab
2026-05-04T15:51:29Z

building docs with SPHINXDIRS=process is too noisy, as it
generates lots of undefined refs. Fixing it is easy: just let
linkify generate html URLs for the broken links when SPHINXDIRS
is used.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 21 +++++++++++++++++++--
1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 4fc894b377e6..1d7d441e281c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -104,10 +104,27 @@ class MaintainersParser:

def linkify(self, text):
"""Linkify all non-wildcard refs to ReST files in Documentation/"""
+
m = self.re_doc.search(text)
if m:
- # maintainers.rst is in a subdirectory, so include "../".
- text = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), text)
+ fname = m.group(1)
+ name = m.group(2)
+ ename = "/" + name
+
+ entry = os.path.relpath(self.base_dir + ename, self.app_dir)
+ full_name = os.path.join(self.base_dir, fname)
+ path = os.path.relpath(full_name, self.app_dir)
+
+ #
+ # When SPHINXDIRS is used, it will try to reference files
+ # outside srctree, causing warnings. To avoid that, point
+ # to the latest official documentation
+ #
+ if path.startswith("../"):
+ html = KERNELDOC_URL + m.group(2) + ".html"
+ text = self.re_doc.sub(f'`{name} <{html}>_`', text)
+ else:
+ text = self.re_doc.sub(f':doc:`{name} <{entry}>`', text)

return text

--
2.54.0