From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 986123C4542; Mon, 27 Apr 2026 13:00:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777294819; cv=none; b=dNYP9VWLxZNZKmyM2BdAVx5dgU3oSS2LmbMgsPnaFxomyHC1XyOLzoCAgBvaRcEujeIlz6UxJY1WD78x4b3jGy0VHWjXVRVYE48DhmzE+q3IDtWt5nKnlsZh/mIjEsv1JZSMdHWmgqJCba8A6oPS9vzF/t+dYZtczli+fUd+zZg= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777294819; c=relaxed/simple; bh=foSitjGjVjWkt3FOsEjErrXwoSNFIILUN9JQwZDwqYk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XcpAdt9SeW3oUJik7kYH6SoNVDRsvfKF6jCgT0KdirGTebkCkm4qImC51RDMOXgQUb1AEkbJb46GlsDt5kAk/DwWTd8ax6thnBEWGFju943HzFOJqwbVpMLoLYfG9QojWsS+xqesPWulRPRU8t4+A8vxmy80hW1oJV516EM2BBQ= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Qvev6HLJ; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Qvev6HLJ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7B883C2BCC4; Mon, 27 Apr 2026 13:00:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777294819; bh=foSitjGjVjWkt3FOsEjErrXwoSNFIILUN9JQwZDwqYk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Qvev6HLJuMayIpthungyNVUdSr2Z2XZPDzRo7epemBAJ5/RSlVHAa5TEp9LxOU8c2 la2K3OpTx3G/d9kIUrhtC5KyoHROHPddBfJqk1OyosBd8OGBRFmMVBftv8lEsdCk4E 83ZpBT8uRn/nDhicLaqZc5mw+jLzEWlBH8S1Qp7uwK4NOMuKTr1GPkvbFk/8Qoskxn UyOZ5smkEZFq1pc9hiy0V4MW/iG0qqRvQFskGQBV411UT0r0AN2SExI2i9Gl0glpoL Skl/brxwB1BfU/adurrwNa1ooEBTwxTXZtVVnBS1557ql3PInU8suRKLk7LFmfwnfG n5Y251VWyMZAw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHLZR-0000000BxDd-2hcX; Mon, 27 Apr 2026 15:00:17 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan Subject: [PATCH v3 10/12] docs: maintainers_include: improve its output Date: Mon, 27 Apr 2026 15:00:10 +0200 Message-ID: X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 8bit Sender: Mauro Carvalho Chehab 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 --- 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