[PATCH v4 08/10] docs: maintainers_include: improve its output

Mauro Carvalho Chehab
2026-04-27T14:22:36Z

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.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
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