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 <[email protected]> --- 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
