* [PATCH 6/8] docs: maintainers_include: add external profile URLs
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
Some subsystem profiles are maintained elsewhere. Add them to
the output.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 28 +++++++++++++++++++--
1 file changed, 26 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index cf428db7599c..f1b8d4b00c2a 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,6 +37,7 @@ class MaintainersParser:
def __init__(self, base_path, path):
self.profiles = {}
+ self.profile_urls = {}
result = list()
result.append(".. _maintainers:")
@@ -81,6 +82,16 @@ class MaintainersParser:
else:
self.profiles[fname] += f", {subsystem_name}"
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ url = match.group(1).strip()
+ if url not in self.profile_urls:
+ if self.profile_urls.get(url) is None:
+ self.profile_urls[url] = subsystem_name
+ else:
+ self.profile_urls[url] += f", {subsystem_name}"
+
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -219,18 +230,31 @@ class MaintainersProfile(Include):
def emit(self, base_path, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- profiles = MaintainersParser(base_path, path).profiles
+ maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ items = sorted(maint.profiles.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
for fname, profile in items:
if profile:
output += f" {profile} <{fname}>\n"
else:
output += f" {fname}\n"
+ output += "\n**External profiles**\n\n"
+
+ items = sorted(maint.profile_urls.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
+ for url, profile in items:
+ if profile:
+ output += f"- {profile} <{url}>\n"
+ else:
+ output += f"- {url}\n"
+
+ output += "\n"
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
--
2.53.0
^ permalink raw reply related
* [PATCH 4/8] docs: auto-generate maintainer entry profile links
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Albert Ou, Alexandre Ghiti, Dan Williams, Mauro Carvalho Chehab,
Palmer Dabbelt, Paul Walmsley, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
Instead of manually creating a TOC tree for them, use the new
tag to auto-generate its TOC.
Co-developed-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <9228f77b0339b8e5dea4a201ab6d4feb30cef5c2.1776176108.git.mchehab+huawei@kernel.org>
---
.../maintainer/maintainer-entry-profile.rst | 24 ++++---------------
.../process/maintainer-handbooks.rst | 19 ++++++++-------
2 files changed, 14 insertions(+), 29 deletions(-)
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 6020d188e13d..58e2af333692 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -92,24 +92,8 @@ full series, or privately send a reminder email. This section might also
list how review works for this code area and methods to get feedback
that are not directly from the maintainer.
-Existing profiles
------------------
+Maintainer Handbooks
+--------------------
-For now, existing maintainer profiles are listed here; we will likely want
-to do something different in the near future.
-
-.. toctree::
- :maxdepth: 1
-
- ../doc-guide/maintainer-profile
- ../nvdimm/maintainer-entry-profile
- ../arch/riscv/patch-acceptance
- ../process/maintainer-soc
- ../process/maintainer-soc-clean-dts
- ../driver-api/media/maintainer-entry-profile
- ../process/maintainer-netdev
- ../driver-api/vfio-pci-device-specific-driver-acceptance
- ../nvme/feature-and-quirk-policy
- ../filesystems/nfs/nfsd-maintainer-entry-profile
- ../filesystems/xfs/xfs-maintainer-entry-profile
- ../mm/damon/maintainer-profile
+For examples of other subsystem handbooks see
+Documentation/process/maintainer-handbooks.rst.
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 3d72ad25fc6a..531985a0fae8 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -7,14 +7,15 @@ The purpose of this document is to provide subsystem specific information
which is supplementary to the general development process handbook
:ref:`Documentation/process <development_process_main>`.
+For developers, see below for all the known subsystem specific guides.
+If the subsystem you are contributing to does not have a guide listed
+here, it is fair to seek clarification of questions raised in
+Documentation/maintainer/maintainer-entry-profile.rst.
+
+For maintainers, consider documenting additional requirements and
+expectations if submissions routinely overlook specific submission
+criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
+
Contents:
-.. toctree::
- :numbered:
- :maxdepth: 2
-
- maintainer-netdev
- maintainer-soc
- maintainer-soc-clean-dts
- maintainer-tip
- maintainer-kvm-x86
+.. maintainers-profile-toc::
--
2.53.0
^ permalink raw reply related
* [PATCH 1/8] docs: maintainers_include: auto-generate maintainer profile TOC
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
Add a feature to allow auto-generating media entry profiles from the
corresponding field inside MAINTAINERS file(s).
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 93 +++++++++++++++++----
1 file changed, 76 insertions(+), 17 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 519ad18685b2..1dac83bf1a65 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,6 +21,8 @@ import sys
import re
import os.path
+from textwrap import indent
+
from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
@@ -30,20 +32,11 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-def setup(app):
- app.add_directive("maintainers-include", MaintainersInclude)
- return dict(
- version = __version__,
- parallel_read_safe = True,
- parallel_write_safe = True
- )
+class MaintainersParser:
+ """Parse MAINTAINERS file(s) content"""
-class MaintainersInclude(Include):
- """MaintainersInclude (``maintainers-include``) directive"""
- required_arguments = 0
-
- def parse_maintainers(self, path):
- """Parse all the MAINTAINERS lines into ReST for human-readability"""
+ def __init__(self, base_path, path):
+ self.profiles = list()
result = list()
result.append(".. _maintainers:")
@@ -78,6 +71,12 @@ class MaintainersInclude(Include):
# Drop needless input whitespace.
line = line.rstrip()
+ match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ if match:
+ fname = os.path.relpath(match.group(1), base_path)
+ if fname not in self.profiles:
+ self.profiles.append(fname)
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -165,12 +164,23 @@ class MaintainersInclude(Include):
for separated in field_content.split('\n'):
result.append(separated)
- output = "\n".join(result)
+ self.output = "\n".join(result)
+
+ # Create a TOC class
+
+class MaintainersInclude(Include):
+ """MaintainersInclude (``maintainers-include``) directive"""
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines into ReST for human-readability"""
+
+ output = MaintainersParser(base_path, path).output
+
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
- self.state_machine.insert_input(
- statemachine.string2lines(output), path)
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
@@ -186,12 +196,61 @@ 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.parse_maintainers(path)
+ lines = self.emit(base_path, path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
+class MaintainersProfile(Include):
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines looking for profile entries"""
+
+ profiles = MaintainersParser(base_path, path).profiles
+
+ output = ".. toctree::\n"
+ output += " :maxdepth: 2\n\n"
+ output += indent("\n".join(profiles), " ")
+
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
+
+ def run(self):
+ """Include the MAINTAINERS file as part of this reST file."""
+ if not self.state.document.settings.file_insertion_enabled:
+ raise self.warning('"%s" directive disabled.' % self.name)
+
+ # Walk up source path directories to find Documentation/../
+ path = self.state_machine.document.attributes['source']
+ path = os.path.realpath(path)
+ tail = path
+ while tail != "Documentation" and tail != "":
+ (path, tail) = os.path.split(path)
+
+ # 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)
+ except IOError as error:
+ raise self.severe('Problems with "%s" directive path:\n%s.' %
+ (self.name, ErrorString(error)))
+
+ return []
+
+def setup(app):
+ app.add_directive("maintainers-include", MaintainersInclude)
+ app.add_directive("maintainers-profile-toc", MaintainersProfile)
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
--
2.53.0
^ permalink raw reply related
* [PATCH 3/8] MAINTAINERS: add maintainer-tip.rst to X86
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
The X86 subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <970434c647aa1e1e9a81c87b4d5fed934d4018a7.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 620219e48f98..a85fcae5f56e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -28560,6 +28560,7 @@ M: Ingo Molnar <mingo@redhat.com>
M: Borislav Petkov <bp@alien8.de>
M: Dave Hansen <dave.hansen@linux.intel.com>
M: x86@kernel.org
+P: Documentation/process/maintainer-tip.rst
R: "H. Peter Anvin" <hpa@zytor.com>
L: linux-kernel@vger.kernel.org
S: Maintained
--
2.53.0
^ permalink raw reply related
* [PATCH 0/8] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-riscv,
workflows, Alexandre Ghiti, Shuah Khan, Dan Williams
Date: Tue, 14 Apr 2026 16:29:03 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
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@kernel.org>
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(-)
--
2.53.0
^ permalink raw reply
* [PATCH 5/8] docs: maintainers_include: use a better title for profiles
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
As we're picking the name of the subsystem from MAINTAINERS,
also use its subsystem name for the titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 1dac83bf1a65..cf428db7599c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -36,7 +36,7 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = list()
+ self.profiles = {}
result = list()
result.append(".. _maintainers:")
@@ -54,6 +54,7 @@ class MaintainersParser:
prev = None
field_prev = ""
field_content = ""
+ subsystem_name = None
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -75,7 +76,10 @@ class MaintainersParser:
if match:
fname = os.path.relpath(match.group(1), base_path)
if fname not in self.profiles:
- self.profiles.append(fname)
+ if self.profiles.get(fname) is None:
+ self.profiles[fname] = subsystem_name
+ else:
+ self.profiles[fname] += f", {subsystem_name}"
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -112,6 +116,8 @@ class MaintainersParser:
output = field_content + "\n\n"
field_content = ""
+ subsystem_name = line.title()
+
# Collapse whitespace in subsystem name.
heading = re.sub(r"\s+", " ", line)
output = output + "%s\n%s" % (heading, "~" * len(heading))
@@ -217,7 +223,13 @@ class MaintainersProfile(Include):
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- output += indent("\n".join(profiles), " ")
+
+ items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ for fname, profile in items:
+ if profile:
+ output += f" {profile} <{fname}>\n"
+ else:
+ output += f" {fname}\n"
self.state_machine.insert_input(statemachine.string2lines(output), path)
--
2.53.0
^ permalink raw reply related
* [PATCH 7/8] docs: maintainers_include: preserve names for files under process/
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
When a maintainer's profile is stored outside process, they're
already included on some other book and the name of the filesystem
may not be there. That's why the logic picks the name from the
subsystem's name.
However, files directly placed together with maintainers-handbooks.rst
(e.g. under Documentation/process/) is a different history: those
aren't placed anywhere, so we can keep using their own names,
letting Sphinx do his thing.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index f1b8d4b00c2a..948746b998a3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -76,11 +76,13 @@ class MaintainersParser:
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
fname = os.path.relpath(match.group(1), base_path)
- if fname not in self.profiles:
+ if fname.startswith("../"):
if self.profiles.get(fname) is None:
self.profiles[fname] = subsystem_name
else:
self.profiles[fname] += f", {subsystem_name}"
+ else:
+ self.profiles[fname] = None
match = re.match(r"P:\s*(https?://.*)", line)
if match:
--
2.53.0
^ permalink raw reply related
* [PATCH 2/8] MAINTAINERS: add an entry for media maintainers profile
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
The media subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <5af4aa6a716228eea4d59dc26b97d642e1e7d419.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index f0b106a4dd96..620219e48f98 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16115,6 +16115,7 @@ S: Maintained
W: https://linuxtv.org
Q: http://patchwork.kernel.org/project/linux-media/list/
T: git git://linuxtv.org/media.git
+P: Documentation/driver-api/media/maintainer-entry-profile.rst
F: Documentation/admin-guide/media/
F: Documentation/devicetree/bindings/media/
F: Documentation/driver-api/media/
--
2.53.0
^ permalink raw reply related
* [PATCH 8/8] docs: maintainers_include: Only show main entry for profiles
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
Instead of showing as a "Contents:" with 2 identation levels,
drop its title and show profiles as a list of entries.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainer-handbooks.rst | 2 --
Documentation/sphinx/maintainers_include.py | 2 +-
2 files changed, 1 insertion(+), 3 deletions(-)
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 531985a0fae8..3821e78aefc0 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -16,6 +16,4 @@ For maintainers, consider documenting additional requirements and
expectations if submissions routinely overlook specific submission
criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
-Contents:
-
.. maintainers-profile-toc::
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 948746b998a3..7ab921820612 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -235,7 +235,7 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
- output += " :maxdepth: 2\n\n"
+ output += " :maxdepth: 1\n\n"
items = sorted(maint.profiles.items(),
key=lambda kv: (kv[1] or "", kv[0]))
--
2.53.0
^ permalink raw reply related
* Re: maintainer profiles
From: Mauro Carvalho Chehab @ 2026-04-15 11:43 UTC (permalink / raw)
To: Randy Dunlap
Cc: Linux Documentation, Linux Kernel Mailing List, Jonathan Corbet,
Linux Kernel Workflows
In-Reply-To: <d8804a85-dd2b-481e-903f-c6fea5d24c97@infradead.org>
On Sat, 11 Apr 2026 16:54:00 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:
> Also, does anyone know why some of these profiles are numbered and some
> are not? See
> https://docs.kernel.org/maintainer/maintainer-entry-profile.html#existing-profiles
> for odd numbering.
Patch 9/8 fixes it, while solving other issues:
- https://lore.kernel.org/linux-doc/cfff2b313d1f79a5919f400020a1b1a4064a7143.1776252056.git.mchehab+huawei@kernel.org/T/#u
Basically, it creates a hidden TOC which is not displayed, creating
this ReST output:
- :doc:`Arm And Arm64 Soc Sub-Architectures (Common Parts) <maintainer-soc>`
- :doc:`Arm/Samsung S3C, S5P And Exynos Arm Architectures <maintainer-soc-clean-dts>`
- :doc:`Arm/Tesla Fsd Soc Support <maintainer-soc-clean-dts>`
- `Audit Subsystem <https://github.com/linux-audit/audit-kernel/blob/main/README.md>`_
- :doc:`Damon <../mm/damon/maintainer-profile>`
- :doc:`Documentation <../doc-guide/maintainer-profile>`
- :doc:`Google Tensor Soc Support <maintainer-soc-clean-dts>`
- :doc:`Kernel Nfsd, Sunrpc, And Lockd Servers <../filesystems/nfs/nfsd-maintainer-entry-profile>`
- :doc:`Kernel Virtual Machine For X86 (Kvm/X86) <maintainer-kvm-x86>`
- :doc:`Libnvdimm Btt: Block Translation Table <../nvdimm/maintainer-entry-profile>`
- :doc:`Libnvdimm Pmem: Persistent Memory Driver <../nvdimm/maintainer-entry-profile>`
- :doc:`Libnvdimm: Non-Volatile Memory Device Subsystem <../nvdimm/maintainer-entry-profile>`
- :doc:`Media Input Infrastructure (V4L/Dvb) <../driver-api/media/maintainer-entry-profile>`
- :doc:`Networking Drivers <maintainer-netdev>`
- :doc:`Networking [General] <maintainer-netdev>`
- :doc:`Risc-V Architecture <../arch/riscv/patch-acceptance>`
- `Rust <https://rust-for-linux.com/contributing>`_
- `Security Subsystem <https://github.com/LinuxSecurityModule/kernel/blob/main/README.md>`_
- `Selinux Security Module <https://github.com/SELinuxProject/selinux-kernel/blob/main/README.md>`_
- :doc:`Vfio Pci Device Specific Drivers <../driver-api/vfio-pci-device-specific-driver-acceptance>`
- :doc:`X86 Architecture (32-Bit And 64-Bit) <maintainer-tip>`
- :doc:`Xfs Filesystem <../filesystems/xfs/xfs-maintainer-entry-profile>`
.. toctree::
:hidden:
../filesystems/xfs/xfs-maintainer-entry-profile
../driver-api/vfio-pci-device-specific-driver-acceptance
maintainer-netdev
../nvdimm/maintainer-entry-profile
maintainer-soc
maintainer-soc-clean-dts
../doc-guide/maintainer-profile
maintainer-kvm-x86
../mm/damon/maintainer-profile
../driver-api/media/maintainer-entry-profile
../arch/riscv/patch-acceptance
../filesystems/nfs/nfsd-maintainer-entry-profile
maintainer-tip
E.g. instead of showing the contents of the TOC tree, it shows a
per-subsystem sorted list of items. The TOC tree is used there just
to avoid warnings that a .rst file is not placed on a TOC.
The advantage of such approach is that there's now one item at
the list for each "P:" tag at MAINTAINERS. All of them are
displayed using the name of the subsystem as described there,
e.g. it outputs:
• Arm And Arm64 Soc Sub-Architectures (Common Parts)
• Arm/Samsung S3C, S5P And Exynos Arm Architectures
• Arm/Tesla Fsd Soc Support
• Audit Subsystem
• Damon
• Documentation
• Google Tensor Soc Support
• Kernel Nfsd, Sunrpc, And Lockd Servers
• Kernel Virtual Machine For X86 (Kvm/X86)
• Libnvdimm Btt: Block Translation Table
• Libnvdimm Pmem: Persistent Memory Driver
• Libnvdimm: Non-Volatile Memory Device Subsystem
• Media Input Infrastructure (V4L/Dvb)
• Networking Drivers
• Networking [General]
• Risc-V Architecture
• Rust
• Security Subsystem
• Selinux Security Module
• Vfio Pci Device Specific Drivers
• X86 Architecture (32-Bit And 64-Bit)
• Xfs Filesystem
Each of entry there with either a cross-reference to a document or
with a reference to an external site.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Randy Dunlap @ 2026-04-15 20:41 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Albert Ou, Jonathan Corbet,
Mauro Carvalho Chehab, Palmer Dabbelt, Paul Walmsley
Cc: linux-doc, linux-kernel, linux-riscv, workflows, Alexandre Ghiti,
Shuah Khan, Dan Williams
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
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@kernel.org>
> To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
> Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
>
> 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@kernel.org>
> 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]
--
~Randy
^ permalink raw reply
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-16 8:00 UTC (permalink / raw)
To: Randy Dunlap
Cc: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley, linux-doc, linux-kernel, linux-riscv, workflows,
Alexandre Ghiti, Shuah Khan, Dan Williams
In-Reply-To: <88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org>
On Wed, 15 Apr 2026 13:41:16 -0700
Randy Dunlap <rdunlap@infradead.org> 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@kernel.org>
> > To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
> > Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
> > Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
> >
> > 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@kernel.org>
> > 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@infradead.org>
Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
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(
^ permalink raw reply related
* Re: [PATCH net] netrom: do some basic forms of validation on incoming frames
From: Jakub Kicinski @ 2026-04-16 16:58 UTC (permalink / raw)
To: linux-hams
Cc: Chris Maness, hugh, Greg KH, Kuniyuki Iwashima, davem, edumazet,
horms, linux-kernel, netdev, pabeni, stable, workflows, yizhe,
f6bvp, Jean-Paul Roubelat, Joerg Reuter, Andreas Koensgen,
Thomas Sailer
In-Reply-To: <CANnsUMFVg9nZnJ_He38O9Ui1YUM_Je7MGO-y_J+oW=TG3jV1bA@mail.gmail.com>
On Sun, 12 Apr 2026 05:56:50 -0700 Chris Maness wrote:
> Thanks for your work, Hugh.
Hi good folks of hamradio.
There was a blip of activity after this thread started but now core
networking maintainers are back to reviewing all the fixes themselves
again.
We would like y'all to set up a git tree so that you can handle all the
incoming AI patches, and send them out as a pull request. This is how
wifi, bluetooth etc. operate. You already have a mailing list so that's
good.
We do not have the capacity to review all the AI generated fixes, and
ignoring security fixes does not feel like an option. I'm planning to
send a PR early next week, shedding some low usage / high CVE count code
I hope you can have the tree in place by then.
^ permalink raw reply
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Randy Dunlap @ 2026-04-16 21:32 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley, linux-doc, linux-kernel, linux-riscv, workflows,
Alexandre Ghiti, Shuah Khan, Dan Williams
In-Reply-To: <20260416100026.3df67a72@foz.lan>
On 4/16/26 1:00 AM, Mauro Carvalho Chehab wrote:
> On Wed, 15 Apr 2026 13:41:16 -0700
> Randy Dunlap <rdunlap@infradead.org> 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@kernel.org>
>>> To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
>>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
>>> Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
>>>
>>> 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@kernel.org>
>>> 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@infradead.org>
> Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> 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(
With that patch I still see 6 warnings:
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]
--
~Randy
^ permalink raw reply
* [PATCH v2 01/11] MAINTAINERS: add an entry for media maintainers profile
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
The media subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <5af4aa6a716228eea4d59dc26b97d642e1e7d419.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index f0b106a4dd96..620219e48f98 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16115,6 +16115,7 @@ S: Maintained
W: https://linuxtv.org
Q: http://patchwork.kernel.org/project/linux-media/list/
T: git git://linuxtv.org/media.git
+P: Documentation/driver-api/media/maintainer-entry-profile.rst
F: Documentation/admin-guide/media/
F: Documentation/devicetree/bindings/media/
F: Documentation/driver-api/media/
--
2.53.0
^ permalink raw reply related
* [PATCH v2 03/11] docs: maintainers_include: auto-generate maintainer profile TOC
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Add a feature to allow auto-generating media entry profiles from the
corresponding field inside MAINTAINERS file(s).
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 93 +++++++++++++++++----
1 file changed, 76 insertions(+), 17 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 519ad18685b2..1dac83bf1a65 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,6 +21,8 @@ import sys
import re
import os.path
+from textwrap import indent
+
from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
@@ -30,20 +32,11 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-def setup(app):
- app.add_directive("maintainers-include", MaintainersInclude)
- return dict(
- version = __version__,
- parallel_read_safe = True,
- parallel_write_safe = True
- )
+class MaintainersParser:
+ """Parse MAINTAINERS file(s) content"""
-class MaintainersInclude(Include):
- """MaintainersInclude (``maintainers-include``) directive"""
- required_arguments = 0
-
- def parse_maintainers(self, path):
- """Parse all the MAINTAINERS lines into ReST for human-readability"""
+ def __init__(self, base_path, path):
+ self.profiles = list()
result = list()
result.append(".. _maintainers:")
@@ -78,6 +71,12 @@ class MaintainersInclude(Include):
# Drop needless input whitespace.
line = line.rstrip()
+ match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ if match:
+ fname = os.path.relpath(match.group(1), base_path)
+ if fname not in self.profiles:
+ self.profiles.append(fname)
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -165,12 +164,23 @@ class MaintainersInclude(Include):
for separated in field_content.split('\n'):
result.append(separated)
- output = "\n".join(result)
+ self.output = "\n".join(result)
+
+ # Create a TOC class
+
+class MaintainersInclude(Include):
+ """MaintainersInclude (``maintainers-include``) directive"""
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines into ReST for human-readability"""
+
+ output = MaintainersParser(base_path, path).output
+
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
- self.state_machine.insert_input(
- statemachine.string2lines(output), path)
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
@@ -186,12 +196,61 @@ 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.parse_maintainers(path)
+ lines = self.emit(base_path, path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
+class MaintainersProfile(Include):
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines looking for profile entries"""
+
+ profiles = MaintainersParser(base_path, path).profiles
+
+ output = ".. toctree::\n"
+ output += " :maxdepth: 2\n\n"
+ output += indent("\n".join(profiles), " ")
+
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
+
+ def run(self):
+ """Include the MAINTAINERS file as part of this reST file."""
+ if not self.state.document.settings.file_insertion_enabled:
+ raise self.warning('"%s" directive disabled.' % self.name)
+
+ # Walk up source path directories to find Documentation/../
+ path = self.state_machine.document.attributes['source']
+ path = os.path.realpath(path)
+ tail = path
+ while tail != "Documentation" and tail != "":
+ (path, tail) = os.path.split(path)
+
+ # 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)
+ except IOError as error:
+ raise self.severe('Problems with "%s" directive path:\n%s.' %
+ (self.name, ErrorString(error)))
+
+ return []
+
+def setup(app):
+ app.add_directive("maintainers-include", MaintainersInclude)
+ app.add_directive("maintainers-profile-toc", MaintainersProfile)
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
--
2.53.0
^ permalink raw reply related
* [PATCH v2 02/11] MAINTAINERS: add maintainer-tip.rst to X86
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
The X86 subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <970434c647aa1e1e9a81c87b4d5fed934d4018a7.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 620219e48f98..a85fcae5f56e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -28560,6 +28560,7 @@ M: Ingo Molnar <mingo@redhat.com>
M: Borislav Petkov <bp@alien8.de>
M: Dave Hansen <dave.hansen@linux.intel.com>
M: x86@kernel.org
+P: Documentation/process/maintainer-tip.rst
R: "H. Peter Anvin" <hpa@zytor.com>
L: linux-kernel@vger.kernel.org
S: Maintained
--
2.53.0
^ permalink raw reply related
* [PATCH v2 05/11] docs: maintainers_include: use a better title for profiles
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
As we're picking the name of the subsystem from MAINTAINERS,
also use its subsystem name for the titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 1dac83bf1a65..cf428db7599c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -36,7 +36,7 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = list()
+ self.profiles = {}
result = list()
result.append(".. _maintainers:")
@@ -54,6 +54,7 @@ class MaintainersParser:
prev = None
field_prev = ""
field_content = ""
+ subsystem_name = None
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -75,7 +76,10 @@ class MaintainersParser:
if match:
fname = os.path.relpath(match.group(1), base_path)
if fname not in self.profiles:
- self.profiles.append(fname)
+ if self.profiles.get(fname) is None:
+ self.profiles[fname] = subsystem_name
+ else:
+ self.profiles[fname] += f", {subsystem_name}"
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -112,6 +116,8 @@ class MaintainersParser:
output = field_content + "\n\n"
field_content = ""
+ subsystem_name = line.title()
+
# Collapse whitespace in subsystem name.
heading = re.sub(r"\s+", " ", line)
output = output + "%s\n%s" % (heading, "~" * len(heading))
@@ -217,7 +223,13 @@ class MaintainersProfile(Include):
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- output += indent("\n".join(profiles), " ")
+
+ items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ for fname, profile in items:
+ if profile:
+ output += f" {profile} <{fname}>\n"
+ else:
+ output += f" {fname}\n"
self.state_machine.insert_input(statemachine.string2lines(output), path)
--
2.53.0
^ permalink raw reply related
* [PATCH v2 00/11] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-riscv,
workflows, Alexandre Ghiti, Shuah Khan, Randy Dunlap,
Dan Williams
Hi 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.
The output is a per-subsystem sorted (*) series of links shown as a
list like this:
- Arm And Arm64 Soc Sub-Architectures (Common Parts)
- Arm/Samsung S3C, S5P And Exynos Arm Architectures
- Arm/Tesla Fsd Soc Support
...
- Xfs Filesystem
Please notice that the series is doing one logical change per patch.
I could have merged some changes altogether, but I opted doing it
in small steps to help reviews. If you prefer, feel free to merge
maintainers_include changes on merge.
There is one interesting side effect of this series: there is no
need to add rst files containing profiles inside a TOC tree: Just
creating the file anywhere inside Documentation and adding a P entry
is enough. Adding them to a TOC won't hurt.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
(*) At the end, I opted to use sorted(), just to ensure it, even
knowing that MAINTAINER entries are supposed to be sorted, as
the cost of sorting ~20 already-sorted entries is negligible.
---
v2:
- I placed the to MAINTAINERS changes at the beginning.
- fix a bug when O=DOCS is used;
- proper handle glob "P" entries (just in case, no profiles use it ATM);
- when SPHINXDIRS=process, instead of producing warnings, point to
entries at https://docs.kernel.org;
- MAINTAINERS parsing now happens just once;
- The output won't be numered for entries inside numered TOC trees;
- TOC tree is now hidden;
- instead of display a TOC tree, it shows a list of profiles,
ordered and named after file system name taken from MAINTAINERS file;
- At the output list, both https and file profiles are shown the same
way.
Mauro Carvalho Chehab (11):
MAINTAINERS: add an entry for media maintainers profile
MAINTAINERS: add maintainer-tip.rst to X86
docs: maintainers_include: auto-generate maintainer profile TOC
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
docs: maintainers_include: improve its output
docs: maintainers_include: fix support for O=dir
docs: maintainers_include: parse MAINTAINERS just once
.../maintainer/maintainer-entry-profile.rst | 24 +--
.../process/maintainer-handbooks.rst | 17 +-
Documentation/sphinx/maintainers_include.py | 161 +++++++++++++++---
MAINTAINERS | 2 +
4 files changed, 150 insertions(+), 54 deletions(-)
--
2.53.0
^ permalink raw reply
* [PATCH v2 04/11] docs: auto-generate maintainer entry profile links
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Albert Ou, Alexandre Ghiti, Dan Williams, Mauro Carvalho Chehab,
Palmer Dabbelt, Paul Walmsley, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Instead of manually creating a TOC tree for them, use the new
tag to auto-generate its TOC.
Co-developed-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <9228f77b0339b8e5dea4a201ab6d4feb30cef5c2.1776176108.git.mchehab+huawei@kernel.org>
---
.../maintainer/maintainer-entry-profile.rst | 24 ++++---------------
.../process/maintainer-handbooks.rst | 19 ++++++++-------
2 files changed, 14 insertions(+), 29 deletions(-)
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 6020d188e13d..58e2af333692 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -92,24 +92,8 @@ full series, or privately send a reminder email. This section might also
list how review works for this code area and methods to get feedback
that are not directly from the maintainer.
-Existing profiles
------------------
+Maintainer Handbooks
+--------------------
-For now, existing maintainer profiles are listed here; we will likely want
-to do something different in the near future.
-
-.. toctree::
- :maxdepth: 1
-
- ../doc-guide/maintainer-profile
- ../nvdimm/maintainer-entry-profile
- ../arch/riscv/patch-acceptance
- ../process/maintainer-soc
- ../process/maintainer-soc-clean-dts
- ../driver-api/media/maintainer-entry-profile
- ../process/maintainer-netdev
- ../driver-api/vfio-pci-device-specific-driver-acceptance
- ../nvme/feature-and-quirk-policy
- ../filesystems/nfs/nfsd-maintainer-entry-profile
- ../filesystems/xfs/xfs-maintainer-entry-profile
- ../mm/damon/maintainer-profile
+For examples of other subsystem handbooks see
+Documentation/process/maintainer-handbooks.rst.
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 3d72ad25fc6a..531985a0fae8 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -7,14 +7,15 @@ The purpose of this document is to provide subsystem specific information
which is supplementary to the general development process handbook
:ref:`Documentation/process <development_process_main>`.
+For developers, see below for all the known subsystem specific guides.
+If the subsystem you are contributing to does not have a guide listed
+here, it is fair to seek clarification of questions raised in
+Documentation/maintainer/maintainer-entry-profile.rst.
+
+For maintainers, consider documenting additional requirements and
+expectations if submissions routinely overlook specific submission
+criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
+
Contents:
-.. toctree::
- :numbered:
- :maxdepth: 2
-
- maintainer-netdev
- maintainer-soc
- maintainer-soc-clean-dts
- maintainer-tip
- maintainer-kvm-x86
+.. maintainers-profile-toc::
--
2.53.0
^ permalink raw reply related
* [PATCH v2 11/11] docs: maintainers_include: parse MAINTAINERS just once
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Change the logic to parse MAINTAINERS file content just once,
while still allowing using it multiple times.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 61 +++++++--------------
1 file changed, 21 insertions(+), 40 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index ae52e8198750..436e7ac42ffc 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,14 +37,13 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-app_dir = "."
+maint_parser = None
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, path):
- global app_dir
-
+ def __init__(self, app_dir, path):
+ self.path = path
self.profile_toc = set()
self.profile_entries = {}
@@ -67,7 +66,6 @@ class MaintainersParser:
subsystem_name = None
base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
- print("BASE DIR", base_dir)
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -105,8 +103,6 @@ class MaintainersParser:
else:
entry = "/" + entry
- print(f"{name}: entry: {entry} FULL: {full_name} path: {path}")
-
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -217,14 +213,17 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
+ global maint_parser
- output = MaintainersParser(path).output
+ path = maint_parser.path
+ output = maint_parser.output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -232,19 +231,8 @@ class MaintainersInclude(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -254,16 +242,17 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines looking for profile entries"""
+ global maint_parser
- maint = MaintainersParser(path)
+ path = maint_parser.path
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
- for profile, entry in sorted(maint.profile_entries.items()):
+ for profile, entry in sorted(maint_parser.profile_entries.items()):
if entry.startswith("http"):
output += f"- `{profile} <{entry}>`_\n"
else:
@@ -276,13 +265,12 @@ class MaintainersProfile(Include):
output += "\n.. toctree::\n"
output += " :hidden:\n\n"
- for fname in maint.profile_toc:
+ for fname in maint_parser.profile_toc:
output += f" {fname}\n"
output += "\n"
- print(output)
-
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -290,19 +278,8 @@ class MaintainersProfile(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -310,13 +287,17 @@ class MaintainersProfile(Include):
return []
def setup(app):
- global app_dir
+ global maint_parser
#
# 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.
#
app_dir = os.fspath(app.srcdir)
+ srctree = os.path.abspath(os.environ["srctree"])
+ path = os.path.join(srctree, "MAINTAINERS")
+
+ maint_parser = MaintainersParser(app_dir, path)
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
--
2.53.0
^ permalink raw reply related
* [PATCH v2 06/11] docs: maintainers_include: add external profile URLs
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Some subsystem profiles are maintained elsewhere. Add them to
the output.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 28 +++++++++++++++++++--
1 file changed, 26 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index cf428db7599c..f1b8d4b00c2a 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,6 +37,7 @@ class MaintainersParser:
def __init__(self, base_path, path):
self.profiles = {}
+ self.profile_urls = {}
result = list()
result.append(".. _maintainers:")
@@ -81,6 +82,16 @@ class MaintainersParser:
else:
self.profiles[fname] += f", {subsystem_name}"
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ url = match.group(1).strip()
+ if url not in self.profile_urls:
+ if self.profile_urls.get(url) is None:
+ self.profile_urls[url] = subsystem_name
+ else:
+ self.profile_urls[url] += f", {subsystem_name}"
+
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -219,18 +230,31 @@ class MaintainersProfile(Include):
def emit(self, base_path, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- profiles = MaintainersParser(base_path, path).profiles
+ maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ items = sorted(maint.profiles.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
for fname, profile in items:
if profile:
output += f" {profile} <{fname}>\n"
else:
output += f" {fname}\n"
+ output += "\n**External profiles**\n\n"
+
+ items = sorted(maint.profile_urls.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
+ for url, profile in items:
+ if profile:
+ output += f"- {profile} <{url}>\n"
+ else:
+ output += f"- {url}\n"
+
+ output += "\n"
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
--
2.53.0
^ permalink raw reply related
* [PATCH v2 08/11] docs: maintainers_include: Only show main entry for profiles
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Instead of showing as a "Contents:" with 2 identation levels,
drop its title and show profiles as a list of entries.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainer-handbooks.rst | 2 --
Documentation/sphinx/maintainers_include.py | 2 +-
2 files changed, 1 insertion(+), 3 deletions(-)
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 531985a0fae8..3821e78aefc0 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -16,6 +16,4 @@ For maintainers, consider documenting additional requirements and
expectations if submissions routinely overlook specific submission
criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
-Contents:
-
.. maintainers-profile-toc::
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 948746b998a3..7ab921820612 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -235,7 +235,7 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
- output += " :maxdepth: 2\n\n"
+ output += " :maxdepth: 1\n\n"
items = sorted(maint.profiles.items(),
key=lambda kv: (kv[1] or "", kv[0]))
--
2.53.0
^ permalink raw reply related
* [PATCH v2 09/11] docs: maintainers_include: improve its output
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
There are three "types" of profiles:
1. Profiles already included inside subsystem-specific documentation.
This is the most common case;
2. Profiles that are hosted externally;
3. Profiles that are at the same location as maintainer-handbooks.rst.
For (3), we need to create a TOC, as they don't exist elsewhere.
Change the logic to create TOC just for (3), prepending the
content of maintainer-handbooks with a sorted entry of all types,
before the TOC.
With such change, we can have an unique sorted list of profiles,
having the subsystem names used there listed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 76 +++++++++++----------
1 file changed, 40 insertions(+), 36 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 7ab921820612..5413c1350bba 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,7 +21,7 @@ import sys
import re
import os.path
-from textwrap import indent
+from glob import glob
from docutils import statemachine
from docutils.parsers.rst import Directive
@@ -36,8 +36,8 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = {}
- self.profile_urls = {}
+ self.profile_toc = set()
+ self.profile_entries = {}
result = list()
result.append(".. _maintainers:")
@@ -73,26 +73,24 @@ class MaintainersParser:
# Drop needless input whitespace.
line = line.rstrip()
+ #
+ # Handle profile entries - either as files or as https refs
+ #
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
- fname = os.path.relpath(match.group(1), base_path)
- if fname.startswith("../"):
- if self.profiles.get(fname) is None:
- self.profiles[fname] = subsystem_name
- else:
- self.profiles[fname] += f", {subsystem_name}"
+ entry = os.path.relpath(match.group(1), base_path)
+ if "*" in entry:
+ for e in glob(entry):
+ self.profile_toc.add(e)
+ self.profile_entries[subsystem_name] = e
else:
- self.profiles[fname] = None
-
- match = re.match(r"P:\s*(https?://.*)", line)
- if match:
- url = match.group(1).strip()
- if url not in self.profile_urls:
- if self.profile_urls.get(url) is None:
- self.profile_urls[url] = subsystem_name
- else:
- self.profile_urls[url] += f", {subsystem_name}"
-
+ self.profile_toc.add(entry)
+ self.profile_entries[subsystem_name] = entry
+ else:
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ entry = match.group(1).strip()
+ self.profile_entries[subsystem_name] = entry
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -234,26 +232,32 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
- output = ".. toctree::\n"
- output += " :maxdepth: 1\n\n"
+ #
+ # Produce a list with all maintainer profiles, sorted by subsystem name
+ #
+ output = ""
- items = sorted(maint.profiles.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for fname, profile in items:
- if profile:
- output += f" {profile} <{fname}>\n"
+ for profile, entry in maint.profile_entries.items():
+ if entry.startswith("http"):
+ if profile:
+ output += f"- `{profile} <{entry}>`_\n"
+ else:
+ output += f"- `<{entry}>_`\n"
else:
- output += f" {fname}\n"
+ if profile:
+ output += f"- :doc:`{profile} <{entry}>`\n"
+ else:
+ output += f"- :doc:`<{entry}>`\n"
- output += "\n**External profiles**\n\n"
+ #
+ # Create a hidden TOC table with all profiles. That allows adding
+ # profiles without needing to add them on any index.rst file.
+ #
+ output += "\n.. toctree::\n"
+ output += " :hidden:\n\n"
- items = sorted(maint.profile_urls.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for url, profile in items:
- if profile:
- output += f"- {profile} <{url}>\n"
- else:
- output += f"- {url}\n"
+ for fname in maint.profile_toc:
+ output += f" {fname}\n"
output += "\n"
--
2.53.0
^ permalink raw reply related
* [PATCH v2 07/11] docs: maintainers_include: preserve names for files under process/
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
When a maintainer's profile is stored outside process, they're
already included on some other book and the name of the filesystem
may not be there. That's why the logic picks the name from the
subsystem's name.
However, files directly placed together with maintainers-handbooks.rst
(e.g. under Documentation/process/) is a different history: those
aren't placed anywhere, so we can keep using their own names,
letting Sphinx do his thing.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index f1b8d4b00c2a..948746b998a3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -76,11 +76,13 @@ class MaintainersParser:
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
fname = os.path.relpath(match.group(1), base_path)
- if fname not in self.profiles:
+ if fname.startswith("../"):
if self.profiles.get(fname) is None:
self.profiles[fname] = subsystem_name
else:
self.profiles[fname] += f", {subsystem_name}"
+ else:
+ self.profiles[fname] = None
match = re.match(r"P:\s*(https?://.*)", line)
if match:
--
2.53.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox