Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab
Date: Thu Apr 16 2026 - 04:02:29 EST
On Wed, 15 Apr 2026 13:41:16 -0700
Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:
> Hi Mauro,
>
> Thanks for tackling this issue.
>
> On 4/15/26 1:52 AM, Mauro Carvalho Chehab wrote:
> > Date: Tue, 14 Apr 2026 16:29:03 +0200
> > From: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> > To: Albert Ou <aou@xxxxxxxxxxxxxxxxx>, Jonathan Corbet <corbet@xxxxxxx>, Dan Williams <djbw@xxxxxxxxxx>, Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>, Palmer Dabbelt <palmer@xxxxxxxxxxx>, Paul Walmsley <pjw@xxxxxxxxxx>
> > Cc: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>, Randy Dunlap <rdunlap@xxxxxxxxxxxxx>, linux-doc@xxxxxxxxxxxxxxx, linux-kernel@xxxxxxxxxxxxxxx, linux-riscv@xxxxxxxxxxxxxxxxxxx, workflows@xxxxxxxxxxxxxxx, Alexandre Ghiti <alex@xxxxxxxx>, Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>
> > Message-ID: <cover.1776176108.git.mchehab+huawei@xxxxxxxxxx>
> >
> > Hi Dan/Jon,
> >
> > This patch series change the way maintainer entry profile links
> > are added to the documentation. Instead of having an entry for
> > each of them at an ReST file, get them from MAINTAINERS content.
> >
> > That should likely make easier to maintain, as there will be a single
> > point to place all such profiles.
> >
> > On this version, I added Dan's text to patch 4.
> >
> > I also added a couple of other patches to improve its output. While
> > I could have them merged at the first patch, I opted to make them
> > separate, as, in case of problems or needed changes, it would be
> > easier to revert or modify the corresponding logic. Also, it should
> > be better to review, in case one wants some changes there.
> >
> > The main changes against RFC are:
> >
> > - now, the TOC will be presented with 1 depth identation level,
> > meaning that it would look like a list;
> > - for files outside Documentation/process, it will use the name of
> > the subsystem with title capitalization for the name of the
> > profile entry;
> > - the logic also parses and produces a list of profiles that are
> > maintained elsewhere, picking its http/https link;
> > - entries are now better sorted: first by subsystem name, then
> > by its name.
> >
> > Suggested-by: Dan Williams <djbw@xxxxxxxxxx>
> > Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
> >
> > Mauro Carvalho Chehab (8):
> > docs: maintainers_include: auto-generate maintainer profile TOC
> > MAINTAINERS: add an entry for media maintainers profile
> > MAINTAINERS: add maintainer-tip.rst to X86
> > docs: auto-generate maintainer entry profile links
> > docs: maintainers_include: use a better title for profiles
> > docs: maintainers_include: add external profile URLs
> > docs: maintainers_include: preserve names for files under process/
> > docs: maintainers_include: Only show main entry for profiles
> >
> > .../maintainer/maintainer-entry-profile.rst | 24 +---
> > .../process/maintainer-handbooks.rst | 17 ++-
> > Documentation/sphinx/maintainers_include.py | 131 +++++++++++++++---
> > MAINTAINERS | 2 +
> > 4 files changed, 128 insertions(+), 46 deletions(-)
>
> When building htmldocs with O=DOCS, I get a bunch of warnings.
> I tested against today's linux-next tree.
>
> The 'make O=DOCS htmldocs' warnings are (subset of all warnings):
>
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-kvm-x86' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/filesystems/xfs/xfs-maintainer-entry-profile' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-soc-clean-dts' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-netdev' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-tip' [toc.not_readable]
>
> linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
>
> linux-next/MAINTAINERS:1: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc' [ref.doc]
> linux-next/MAINTAINERS:2: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> linux-next/MAINTAINERS:3: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> linux-next/MAINTAINERS:5: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
> linux-next/MAINTAINERS:6: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
Heh, os.path.relpath() does the wrong thing here.
The enclosed patch should handle it better.
Thanks,
Mauro
[PATCH] docs: maintainers_include: fix support for O=dir
os.path.relpath() will do the wrong thing with O=dir, as the build
system uses "cd <dir>" internally.
Solve it by using app.srcdir, which, on normal cases, point to
Documentation/, or, when SPHINXDIRS=process, it will be set with
Documentation/process.
While here, remove a dead code while writing maintainer profiles,
as now all entries should have both profile and entry.
Reported-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@xxxxxxxxxxxxx/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 5413c1350bba..fff9bdd55a56 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -27,15 +27,24 @@ from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
+#
+# Base URL for intersphinx-like links to maintainer profiles
+#
+KERNELDOC_URL = "https://docs.kernel.org/";
+
def ErrorString(exc): # Shamelessly stolen from docutils
return f'{exc.__class__.__name}: {exc}'
__version__ = '1.0'
+base_dir = "."
+
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, base_path, path):
+ def __init__(self, path):
+ global base_dir
+
self.profile_toc = set()
self.profile_entries = {}
@@ -76,9 +85,18 @@ class MaintainersParser:
#
# Handle profile entries - either as files or as https refs
#
- match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ match = re.match(r"P:\s*Documentation(/\S+)\.rst", line)
if match:
- entry = os.path.relpath(match.group(1), base_path)
+ entry = os.path.relpath(match.group(1), base_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 entry.startswith("../"):
+ entry = KERNELDOC_URL + match.group(1) + ".html"
+
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -189,10 +207,10 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
- output = MaintainersParser(base_path, path).output
+ output = MaintainersParser(path).output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -213,11 +231,10 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -227,27 +244,20 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- maint = MaintainersParser(base_path, path)
+ maint = MaintainersParser(path)
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
-
- for profile, entry in maint.profile_entries.items():
+ for profile, entry in sorted(maint.profile_entries.items()):
if entry.startswith("http"):
- if profile:
- output += f"- `{profile} <{entry}>`_\n"
- else:
- output += f"- `<{entry}>_`\n"
+ output += f"- `{profile} <{entry}>`_\n"
else:
- if profile:
- output += f"- :doc:`{profile} <{entry}>`\n"
- else:
- output += f"- :doc:`<{entry}>`\n"
+ output += f"- :doc:`{profile} <{entry}>`\n"
#
# Create a hidden TOC table with all profiles. That allows adding
@@ -277,11 +287,10 @@ class MaintainersProfile(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -289,6 +298,15 @@ class MaintainersProfile(Include):
return []
def setup(app):
+ global base_dir
+
+ #
+ # partition will pick the path after Documentation.
+ # NOTE: we're using os.fspath() here because of a Sphinx warning:
+ # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
+ #
+ _, _, base_dir = os.fspath(app.srcdir).partition("Documentation")
+
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
return dict(