From nobody Sun Jun 14 02:31:57 2026 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 DCDF63DE431; Mon, 4 May 2026 15:51:28 +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=1777909888; cv=none; b=TzAqnGBvOydvtsyUwuJsV9PuZfyjrWAqJoyZNkJWExVgnAgHzS3MizXmUtw7gWAMJelTvLOTGSZdpq+YtqrKOLrmS1YHpfPggFZTdWdUPvLiyLN5d3ree9GZAA+/Jh5gx2BgnFvw5c2ECKRaoznxUYeygLjU9CKmaWpzXa3KBtA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909888; c=relaxed/simple; bh=yjJsWgNJPSHvj8gL365g1AVkk3a95wZI901VABGTMZs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=R7aLu7brfSlXs35pQ6Ic00i0Jm6wH1YOLEDW/8eGfawVQV+jt1g/xHMuyqgbUhweNe/9w+hItewpS1JxbBHovowP2FrsaitPuqFR357hLIgkm5w7CfS43yWa4u04ifOlk9DS9lHo0sa6WqCGJ+ea1zW4YV7+QtyFMX3jFtmsI3A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gmmGL6em; 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="gmmGL6em" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 76C0BC2BCF6; Mon, 4 May 2026 15:51:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909888; bh=yjJsWgNJPSHvj8gL365g1AVkk3a95wZI901VABGTMZs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gmmGL6emdNRQ7dPqxKWSw/cJoYBQ4Po+Lf9FlPD6yknk+sKzrXVqWa2V9HOcbif6m GO4F+GUhorUKbIHRyyuIKz1UJedYFDANLaUMpt4xJkByfWZaRM7pCpwFsDPFN8C37J pwiKSyer5fzpTXe3Rws1BmdZS/e4qFEHTn4b6CRBp2OSr85sw+A0NhQchgdKI422Rz juNQ9O8WynYpKCBKvGbdVpgWP+ZPlInR8s0jhIVby78XRjZj0+emZLfQUnwb8i9MRU xOJo4bBKjC+q7u51gq738I0jvKt6SJfQQOhKhykXucEYAQtQSOBp4KuKnu98EnrVcr DL40l8MI6JbHg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZu-0000000Ey5Y-2UCb; Mon, 04 May 2026 17:51:26 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Shuah Khan Subject: [PATCH 1/9] docs: maintainers_include: keep hidden TOC sorted Date: Mon, 4 May 2026 17:51:10 +0200 Message-ID: <899e9223d7533996b5a176d2b7b7c5718821cc1e.1777908711.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab There's no practical difference on keeping it sorted, but it helps a lot when checking for differences after patches to the tool. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 1b9ece431386..c7f9911ae45b 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -265,7 +265,7 @@ class MaintainersProfile(Include): output +=3D "\n.. toctree::\n" output +=3D " :hidden:\n\n" =20 - for fname in maint_parser.profile_toc: + for fname in sorted(maint_parser.profile_toc): output +=3D f" {fname}\n" =20 output +=3D "\n" --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 DCE8A3DF019; Mon, 4 May 2026 15:51:28 +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=1777909888; cv=none; b=Ug8fWk3lqccTC39y4+j0bMz08DZZUk/ACxK7b7Wl9piqqMaab+ye5HqHBAJtG74bmqXtYimHe8JycucZlFiD59uiuIj3HnFpczjwC0rpleb8IWEwBWvHtJhOiBPeVZbYBgFNz3HA4H8hw+DkPoKsggNtQod1nr1omTv8i0YAbvs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909888; c=relaxed/simple; bh=SZ479FGDm0wvtVJRY64Rny25k4jq7VQuvT+6JysK1C4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DDAVpsUa7GmEZv9ajBvXBntmtuAArMGBLweartChBUxMn3CyyKWscXhUjITuiErrcatwAbsH2G0RW5dQ19PpBz0duUnwz4KRItPrqBHpUx7HjuKJUOcFvpFcRBx1ik2pf70F4N5xY1bIgCoBzJHQ919Q0jQ5TWdQwx21vIk13Q4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=CPWw4xHl; 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="CPWw4xHl" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A5435C2BCFB; Mon, 4 May 2026 15:51:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909888; bh=SZ479FGDm0wvtVJRY64Rny25k4jq7VQuvT+6JysK1C4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CPWw4xHlyVHyf22fcgjAnzXoTuO121JrQb28FFtkr343yuZZhOuJbaHzFiODOPqkW IkRo3lYOAUS8FjhHtb0WrMtA+YTyJFgEJx3cXVpSShEONWl+8uimHmYs7EqVVToHHi K2n52JTtlTmkeRvnTQDfa+YB95nmVeqCVHWNfnu8JSXI70631AsYQ4pB+fycDDrgLP tc+tlyoy00Bi1XVOTibdIW7qg4QQmzbWpqqlr2JeT62KnnxDiaygBlQc/uz92F8Ylo PdUBhP2FCoyBMg7Ti7Eys1lYrhgVvX46ZpBAEEXEmvjJrXyDOTOWav036KCrc6iFXm apJ1m4J73Rblw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZu-0000000Ey6j-3CkK; Mon, 04 May 2026 17:51:26 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Andrew Morton , Joe Perches , Matteo Croce , Shuah Khan , Matteo Croce Subject: [PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions Date: Mon, 4 May 2026 17:51:11 +0200 Message-ID: <31f673089e2a83dc1fee17d47784579874476ca5.1777908711.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab From: Matteo Croce Escape '**' in the MAINTAINERS descriptions section to prevent reStructuredText from interpreting it as bold/strong inline markup, which causes a warning when running 'make htmldocs'. Fixes: 420849332f9f ("get_maintainer: add ** glob pattern support") Signed-off-by: Matteo Croce Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index c7f9911ae45b..e679acf0633d 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -127,7 +127,8 @@ class MaintainersParser: output =3D None if descriptions: # Escape the escapes in preformatted text. - output =3D "| %s" % (line.replace("\\", "\\\\")) + output =3D "| %s" % (line.replace("\\", "\\\\") + .replace("**", "\\**")) # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName m =3D re.search(r"\s(\S):\s", line) --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 6A57B3E1234; Mon, 4 May 2026 15:51:29 +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=1777909889; cv=none; b=rLiWvmvrkxyhJ49m0z15vzJOka3MFvh+pEXw02UuZyBjxUABf34lQ7c1aH41Y9cUgblJ19J/M8pCW5DPcK8xogjF8j6DkMJFHse+TjP9cp9YYHtZK7XGQzCSjHYVC3OuBfBorse7N0qvYQunqNOccuq3Hfw7xjhnVQvTYAdbmQE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909889; c=relaxed/simple; bh=0ZF7C2vym0JWYc+Iq2I2h3qGDgn5cwCC8/0LA9SeTms=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=H3QzesEr2PRWdXAQV5mTwyPUucHkVKSZk9Yq4b4I39sI/2NlfyZYQv1CrFFGzPFEIdhh4lAwglQbY8OU/F6c1kUCuuJJs7Lxw60lyutAIH+V4/cnUG0iPRv7MkbtokdBO4eTuWtGyOpp8U2NU2j615tqM9lyPz0ld8b+ukjcLck= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fg+WKY03; 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="fg+WKY03" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D8025C2BCFA; Mon, 4 May 2026 15:51:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909889; bh=0ZF7C2vym0JWYc+Iq2I2h3qGDgn5cwCC8/0LA9SeTms=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fg+WKY03hSuZiANPYfSujOYx0ChH4Br/u8ib8e+HnvTpjcn1qyswR5cyhhpkpD1MP kQ/iGRAALSz38h79cD07i4AZj5yXeFJjoU4bjEzt4LumggVC/Zj1sVwfhmkP8pZTZR n7D1OgtIced81FX080QvcPjge4BXvR1T6s1D8Mk9FML1Sa1P3mVo8oJoKSFD+ZCOxA KtDQE2UGxlRMivU/pZswZeNtt1oONyJzB/XMYNvMiMXTaz8KjPawJofiief6RpPAv/ fU1+b2g7V2cJ8zzEYRKhoyc4l8pmAl0JbyMQEX42q/MNSMk+jok6AEunYPGcSnge+A HCkRMzmtu3KXA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZu-0000000Ey7u-3v80; Mon, 04 May 2026 17:51:26 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Shuah Khan Subject: [PATCH 3/9] docs: maintainers_include.py: split state machine on multiple funcs Date: Mon, 4 May 2026 17:51:12 +0200 Message-ID: <7cdfae61b68c7613663ddd528020f6b4a4ccf8ec.1777908711.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab Instead of one big __init__ code, split the MaintainersParser code in a way that the state machine remains on __init__, but the actual parser for descriptions and subsystems are moved to separate functions. To make parser easier, instead storing parsed results on a list, place them directly on a string. That granted 15% of performance increase(*) with Python 3.14 and made the logic simpler. (*) measured by creating a new directory under Documentation/, and placing justmaintainers.rst and an index file there, building it via sphinx-build-wrapper. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 299 +++++++++++--------- 1 file changed, 159 insertions(+), 140 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index e679acf0633d..8867ecc0aad3 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -47,168 +47,187 @@ class MaintainersParser: self.profile_toc =3D set() self.profile_entries =3D {} =20 - result =3D list() - result.append(".. _maintainers:") - result.append("") + self.output =3D ".. _maintainers:\n\n" =20 # Poor man's state machine. - descriptions =3D False - maintainers =3D False - subsystems =3D False + self.descriptions =3D False + self.maintainers =3D False + self.subsystems =3D False =20 # Field letter to field name mapping. - field_letter =3D None - fields =3D dict() + self.field_letter =3D None + self.fields =3D dict() + + self.field_prev =3D "" + self.field_content =3D "" + self.subsystem_name =3D None + + self.app_dir =3D app_dir + self.base_dir, self.doc_dir, self.sphinx_dir =3D app_dir.partition= ("Documentation") + + self.re_doc =3D re.compile(r'(Documentation/([^\s\?\*]*)\.rst)') =20 prev =3D None - field_prev =3D "" - field_content =3D "" - subsystem_name =3D None - - base_dir, doc_dir, sphinx_dir =3D app_dir.partition("Documentation= ") - for line in open(path): - # Have we reached the end of the preformatted Descriptions tex= t? - if descriptions and line.startswith('Maintainers'): - descriptions =3D False - # Ensure a blank line following the last "|"-prefixed line. - result.append("") - - # Start subsystem processing? This is to skip processing the t= ext - # between the Maintainers heading and the first subsystem name. - if maintainers and not subsystems: + if self.descriptions: + self.parse_descriptions(line) + elif self.maintainers and not self.subsystems: if re.search('^[A-Z0-9]', line): - subsystems =3D True - - # Drop needless input whitespace. - line =3D line.rstrip() - - # - # Handle profile entries - either as files or as https refs - # - match =3D re.match(rf"P:\s*({doc_dir})(/\S+)\.rst", line) - if match: - name =3D "".join(match.groups()) - entry =3D os.path.relpath(base_dir + name, app_dir) - - full_name =3D os.path.join(base_dir, name) - path =3D os.path.relpath(full_name, app_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 path.startswith("../"): - entry =3D KERNELDOC_URL + match.group(2) + ".html" + self.subsystems =3D True + self.parse_subsystems(line) else: - entry =3D "/" + entry - - if "*" in entry: - for e in glob(entry): - self.profile_toc.add(e) - self.profile_entries[subsystem_name] =3D e - else: - self.profile_toc.add(entry) - self.profile_entries[subsystem_name] =3D entry - else: - match =3D re.match(r"P:\s*(https?://.*)", line) - if match: - entry =3D match.group(1).strip() - self.profile_entries[subsystem_name] =3D entry - - # Linkify all non-wildcard refs to ReST files in Documentation= /. - pat =3D r'(Documentation/([^\s\?\*]*)\.rst)' - m =3D re.search(pat, line) - if m: - # maintainers.rst is in a subdirectory, so include "../". - line =3D re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.= group(2)), line) - - # Check state machine for output rendering behavior. - output =3D None - if descriptions: - # Escape the escapes in preformatted text. - output =3D "| %s" % (line.replace("\\", "\\\\") - .replace("**", "\\**")) - # Look for and record field letter to field name mappings: - # R: Designated *reviewer*: FullName - m =3D re.search(r"\s(\S):\s", line) - if m: - field_letter =3D m.group(1) - if field_letter and not field_letter in fields: - m =3D re.search(r"\*([^\*]+)\*", line) - if m: - fields[field_letter] =3D m.group(1) - elif subsystems: - # Skip empty lines: subsystem parser adds them as needed. - if len(line) =3D=3D 0: - continue - # Subsystem fields are batched into "field_content" - if line[1] !=3D ':': - # Render a subsystem entry as: - # SUBSYSTEM NAME - # ~~~~~~~~~~~~~~ - - # Flush pending field content. - output =3D field_content + "\n\n" - field_content =3D "" - - subsystem_name =3D line.title() - - # Collapse whitespace in subsystem name. - heading =3D re.sub(r"\s+", " ", line) - output =3D output + "%s\n%s" % (heading, "~" * len(hea= ding)) - field_prev =3D "" - else: - # Render a subsystem field as: - # :Field: entry - # entry... - field, details =3D line.split(':', 1) - details =3D details.strip() - - # Mark paths (and regexes) as literal text for improved - # readability and to escape any escapes. - if field in ['F', 'N', 'X', 'K']: - # But only if not already marked :) - if not ':doc:' in details: - details =3D '``%s``' % (details) - - # Comma separate email field continuations. - if field =3D=3D field_prev and field_prev in ['M', 'R'= , 'L']: - field_content =3D field_content + "," - - # Do not repeat field names, so that field entries - # will be collapsed together. - if field !=3D field_prev: - output =3D field_content + "\n" - field_content =3D ":%s:" % (fields.get(field, fiel= d)) - field_content =3D field_content + "\n\t%s" % (details) - field_prev =3D field + self.output +=3D line + elif self.subsystems: + self.parse_subsystems(line) else: - output =3D line - - # Re-split on any added newlines in any above parsing. - if output !=3D None: - for separated in output.split('\n'): - result.append(separated) + self.output +=3D line =20 # Update the state machine when we find heading separators. if line.startswith('----------'): if prev.startswith('Descriptions'): - descriptions =3D True + self.descriptions =3D True if prev.startswith('Maintainers'): - maintainers =3D True + self.maintainers =3D True =20 # Retain previous line for state machine transitions. prev =3D line =20 # Flush pending field contents. - if field_content !=3D "": - for separated in field_content.split('\n'): - result.append(separated) + if self.field_content: + self.output +=3D self.field_content + "\n\n" =20 - self.output =3D "\n".join(result) + self.output =3D self.output.rstrip() + + def parse_descriptions(self, line): + """Handle contents of the descriptions section.""" + + # Have we reached the end of the preformatted Descriptions text? + if line.startswith('Maintainers'): + self.descriptions =3D False + self.output +=3D "\n" + line + return + + # Linkify all non-wildcard refs to ReST files in Documentation/. + m =3D self.re_doc.search(line) + if m: + # maintainers.rst is in a subdirectory, so include "../". + line =3D self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.= group(2)), line) + + # Escape the escapes in preformatted text. + output =3D "| %s" % (line.replace("\\", "\\\\") + .replace("**", "\\**")) + + # Look for and record field letter to field name mappings: + # R: Designated *reviewer*: FullName + m =3D re.search(r"\s(\S):\s", line) + if m: + self.field_letter =3D m.group(1) + + if self.field_letter and self.field_letter not in self.fields: + m =3D re.search(r"\*([^\*]+)\*", line) + if m: + self.fields[self.field_letter] =3D m.group(1) + + # Append parsed content to self.output + self.output +=3D output + + def parse_subsystems(self, line): + """Handle contents of the per-subsystem sections.""" + + # Drop needless input whitespace. + line =3D line.rstrip() + + # + # Handle profile entries - either as files or as https refs + # + match =3D re.match(rf"P:\s*({self.doc_dir})(/\S+)\.rst", line) + if match: + name =3D "".join(match.groups()) + entry =3D os.path.relpath(self.base_dir + name, self.app_dir) + + full_name =3D os.path.join(self.base_dir, name) + path =3D os.path.relpath(full_name, self.app_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 path.startswith("../"): + entry =3D KERNELDOC_URL + match.group(2) + ".html" + else: + entry =3D "/" + entry + + if "*" in entry: + for e in glob(entry): + self.profile_toc.add(e) + self.profile_entries[self.subsystem_name] =3D e + else: + self.profile_toc.add(entry) + self.profile_entries[self.subsystem_name] =3D entry + else: + match =3D re.match(r"P:\s*(https?://.*)", line) + if match: + entry =3D match.group(1).strip() + self.profile_entries[self.subsystem_name] =3D entry + + # Linkify all non-wildcard refs to ReST files in Documentation/. + m =3D self.re_doc.search(line) + if m: + # maintainers.rst is in a subdirectory, so include "../". + line =3D self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.= group(2)), line) + + # Check state machine for output rendering behavior. + output =3D None + if self.subsystems: + # Skip empty lines: subsystem parser adds them as needed. + if len(line) =3D=3D 0: + return + # Subsystem fields are batched into "field_content" + if line[1] !=3D ':': + # Render a subsystem entry as: + # SUBSYSTEM NAME + # ~~~~~~~~~~~~~~ + # Flush pending field content. + output =3D self.field_content + "\n\n" + self.field_content =3D "" + + self.subsystem_name =3D line.title() + + # Collapse whitespace in subsystem name. + heading =3D re.sub(r"\s+", " ", line) + output =3D output + "%s\n%s" % (heading, "~" * len(heading= )) + self.field_prev =3D "" + else: + # Render a subsystem field as: + # :Field: entry + # entry... + field, details =3D line.split(':', 1) + details =3D details.strip() + + # Mark paths (and regexes) as literal text for improved + # readability and to escape any escapes. + if field in ['F', 'N', 'X', 'K']: + # But only if not already marked :) + if not ':doc:' in details: + details =3D '``%s``' % (details) + + # Comma separate email field continuations. + if field =3D=3D self.field_prev and self.field_prev in ['M= ', 'R', 'L']: + self.field_content =3D self.field_content + "," + + # Do not repeat field names, so that field entries + # will be collapsed together. + if field !=3D self.field_prev: + output =3D self.field_content + "\n" + self.field_content =3D ":%s:" % (self.fields.get(field= , field)) + self.field_content =3D self.field_content + "\n\t%s" % (de= tails) + self.field_prev =3D field + elif not self.descriptions: + output =3D line + + if output is not None: + self.output +=3D output + "\n" =20 - # Create a TOC class =20 class MaintainersInclude(Include): """MaintainersInclude (``maintainers-include``) directive""" --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 3AD033E120D; Mon, 4 May 2026 15:51:29 +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=1777909889; cv=none; b=So58Mqm3JepzrjktKsJjbqdtt6SnuZMPdhzYSkDGeDlqflk4DAB5kmqPimLgCmUpZMCscLHYopX55lpMycEcaYejlOQgoZ+D9UF1bJnWqaeUyH3wKQ53aCf4m9n0hsbRyZ4CU/kTcgbMnp2olVNRuyzrBe8Y131BLKNyjDMD0vs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909889; c=relaxed/simple; bh=a0JKQlQp4GzAqop5uVBSnDqg5QnqT1A1PJcWeMOknHE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=PpM+F0ryGuCM86RcTSXmlSw+Fl5aPanaZ/UJzX+6n8ssW0OjlHJRYaNpM5qqVyATYC6nmSZXo77kZM1QoEPcP1kBiGpjtBLYggeJX0kqrJ9Y9lUiYetFqv3ic96NytTOc7TD6dVJgaMnqm1kjY9VjmJiGGu3labLvcKqvbY3K7M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RcX+4bQd; 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="RcX+4bQd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DDB52C2BCFC; Mon, 4 May 2026 15:51:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909889; bh=a0JKQlQp4GzAqop5uVBSnDqg5QnqT1A1PJcWeMOknHE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RcX+4bQd5rFL5jev4cJp/gTZRKX3lHU/XCWg8qoIoDZmlHYtU+YhguLzCOlvFJmqs mHp7EmxMyUqaIGKEufjqV4CviB4EsbhKVh4fTmnt+wYrwYq9NatZ91wpCpm39a3R/2 7GjNw4oS7ZDmLXa3zsqA6T2M5cd36yoHr2eN2pSg1Ok8eLVy1Q9feTN0G5Kg1z9fnH Jm+45pvrbbgUarNDHDpmennHqTGcgclaz5UBJTsFFxp6ze+zM68Rzh1nIKhHMPJVH2 /W/TFywnTnFsEelw3tF/TO4Cw5NaM6PGvk4TiEbFDI17mzVP9fgaPSizCz/vgHHw83 Q9WT3KvFZBACA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZv-0000000Ey95-0RJv; Mon, 04 May 2026 17:51:27 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Shuah Khan Subject: [PATCH 4/9] docs: maintainers_include: cleanup the code Date: Mon, 4 May 2026 17:51:13 +0200 Message-ID: X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab Simplify the logic without affecting the output result. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 186 ++++++++++---------- 1 file changed, 92 insertions(+), 94 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 8867ecc0aad3..4fc894b377e6 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -44,10 +44,6 @@ class MaintainersParser: =20 def __init__(self, app_dir, path): self.path =3D path - self.profile_toc =3D set() - self.profile_entries =3D {} - - self.output =3D ".. _maintainers:\n\n" =20 # Poor man's state machine. self.descriptions =3D False @@ -67,6 +63,13 @@ class MaintainersParser: =20 self.re_doc =3D re.compile(r'(Documentation/([^\s\?\*]*)\.rst)') =20 + # + # Output variables with maintainers content to be stored + # + self.profile_toc =3D set() + self.profile_entries =3D {} + self.output =3D ".. _maintainers:\n\n" + prev =3D None for line in open(path): if self.descriptions: @@ -98,6 +101,16 @@ class MaintainersParser: =20 self.output =3D self.output.rstrip() =20 + + def linkify(self, text): + """Linkify all non-wildcard refs to ReST files in Documentation/""" + m =3D self.re_doc.search(text) + if m: + # maintainers.rst is in a subdirectory, so include "../". + text =3D self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.= group(2)), text) + + return text + def parse_descriptions(self, line): """Handle contents of the descriptions section.""" =20 @@ -107,15 +120,9 @@ class MaintainersParser: self.output +=3D "\n" + line return =20 - # Linkify all non-wildcard refs to ReST files in Documentation/. - m =3D self.re_doc.search(line) - if m: - # maintainers.rst is in a subdirectory, so include "../". - line =3D self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.= group(2)), line) - # Escape the escapes in preformatted text. - output =3D "| %s" % (line.replace("\\", "\\\\") - .replace("**", "\\**")) + line =3D self.linkify(line).replace("\\", "\\\\").replace("**", "\= \**") + self.output +=3D "| " + line =20 # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName @@ -128,105 +135,96 @@ class MaintainersParser: if m: self.fields[self.field_letter] =3D m.group(1) =20 - # Append parsed content to self.output - self.output +=3D output - def parse_subsystems(self, line): """Handle contents of the per-subsystem sections.""" =20 # Drop needless input whitespace. line =3D line.rstrip() =20 + # Skip empty lines: subsystem parser adds them as needed. + if not line: + return + + # Subsystem fields are batched into "field_content" + if line[1] !=3D ':': + line =3D self.linkify(line) + + # Render a subsystem entry as: + # SUBSYSTEM NAME + # ~~~~~~~~~~~~~~ + # Flush pending field content. + self.output +=3D self.field_content + "\n\n" + self.field_content =3D "" + + self.subsystem_name =3D line.title() + + # Collapse whitespace in subsystem name. + heading =3D re.sub(r"\s+", " ", line) + self.output +=3D "%s\n%s" % (heading, "~" * len(heading)) + "\= n" + self.field_prev =3D "" + + return + + # Render a subsystem field as: + # :Field: entry + # entry... + field, details =3D line.split(':', 1) + details =3D details.strip() + # # Handle profile entries - either as files or as https refs # - match =3D re.match(rf"P:\s*({self.doc_dir})(/\S+)\.rst", line) - if match: - name =3D "".join(match.groups()) - entry =3D os.path.relpath(self.base_dir + name, self.app_dir) - - full_name =3D os.path.join(self.base_dir, name) - path =3D os.path.relpath(full_name, self.app_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 path.startswith("../"): - entry =3D KERNELDOC_URL + match.group(2) + ".html" - else: - entry =3D "/" + entry - - if "*" in entry: - for e in glob(entry): - self.profile_toc.add(e) - self.profile_entries[self.subsystem_name] =3D e - else: - self.profile_toc.add(entry) - self.profile_entries[self.subsystem_name] =3D entry - else: - match =3D re.match(r"P:\s*(https?://.*)", line) + if field =3D=3D "P": + match =3D self.re_doc.match(details) if match: - entry =3D match.group(1).strip() - self.profile_entries[self.subsystem_name] =3D entry + name =3D "".join(match.groups()) + entry =3D os.path.relpath(self.base_dir + name, self.app_d= ir) =20 - # Linkify all non-wildcard refs to ReST files in Documentation/. - m =3D self.re_doc.search(line) - if m: - # maintainers.rst is in a subdirectory, so include "../". - line =3D self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.= group(2)), line) + full_name =3D os.path.join(self.base_dir, name) + path =3D os.path.relpath(full_name, self.app_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 path.startswith("../"): + entry =3D KERNELDOC_URL + "/" + match.group(2) + ".htm= l" + else: + entry =3D "/" + entry =20 - # Check state machine for output rendering behavior. - output =3D None - if self.subsystems: - # Skip empty lines: subsystem parser adds them as needed. - if len(line) =3D=3D 0: - return - # Subsystem fields are batched into "field_content" - if line[1] !=3D ':': - # Render a subsystem entry as: - # SUBSYSTEM NAME - # ~~~~~~~~~~~~~~ - # Flush pending field content. - output =3D self.field_content + "\n\n" - self.field_content =3D "" - - self.subsystem_name =3D line.title() - - # Collapse whitespace in subsystem name. - heading =3D re.sub(r"\s+", " ", line) - output =3D output + "%s\n%s" % (heading, "~" * len(heading= )) - self.field_prev =3D "" + if "*" in entry: + for e in glob(entry): + self.profile_toc.add(e) + self.profile_entries[self.subsystem_name] =3D e + else: + self.profile_toc.add(entry) + self.profile_entries[self.subsystem_name] =3D entry else: - # Render a subsystem field as: - # :Field: entry - # entry... - field, details =3D line.split(':', 1) - details =3D details.strip() + match =3D re.match(r"(https?://.*)", details) + if match: + entry =3D match.group(1).strip() + self.profile_entries[self.subsystem_name] =3D entry =20 - # Mark paths (and regexes) as literal text for improved - # readability and to escape any escapes. - if field in ['F', 'N', 'X', 'K']: - # But only if not already marked :) - if not ':doc:' in details: - details =3D '``%s``' % (details) + details =3D self.linkify(details) =20 - # Comma separate email field continuations. - if field =3D=3D self.field_prev and self.field_prev in ['M= ', 'R', 'L']: - self.field_content =3D self.field_content + "," + # Mark paths (and regexes) as literal text for improved + # readability and to escape any escapes. + if field in ['F', 'N', 'X', 'K']: + # But only if not already marked :) + if not ':doc:' in details: + details =3D '``%s``' % (details) =20 - # Do not repeat field names, so that field entries - # will be collapsed together. - if field !=3D self.field_prev: - output =3D self.field_content + "\n" - self.field_content =3D ":%s:" % (self.fields.get(field= , field)) - self.field_content =3D self.field_content + "\n\t%s" % (de= tails) - self.field_prev =3D field - elif not self.descriptions: - output =3D line + # Comma separate email field continuations. + if field =3D=3D self.field_prev and self.field_prev in ['M', 'R', = 'L']: + self.field_content =3D self.field_content + "," =20 - if output is not None: - self.output +=3D output + "\n" + # Do not repeat field names, so that field entries + # will be collapsed together. + if field !=3D self.field_prev: + self.output +=3D self.field_content + "\n\n" + self.field_content =3D ":%s:" % (self.fields.get(field, field)) + self.field_content =3D self.field_content + "\n\t%s" % (details) + self.field_prev =3D field =20 =20 class MaintainersInclude(Include): --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 556473E1216; Mon, 4 May 2026 15:51:29 +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=1777909889; cv=none; b=gt0mRHK0iaZY8PswSQDAs7ihHY7j8GLEqCEgkFwfObmGkJCFaBtm+WdJdCXZc5cU6qE4S46N/2h4qMf9ErJtr5CVuSGLOL96pXT6Zxpr21bKn3xshzngpB/Oh11Oot6BtN5qyQ1JcXC9H6VaakNGNHDif1dhWJIEvPIXrsGNZa4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909889; c=relaxed/simple; bh=UuCZFcJnawl6nLf6W20Xv9a5MwXy3NjFTm5AuWY4wyg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=mo0n9eK8nMP7ks1ZWqXnRL0FjKWd3Sl2M8q8rLhoh5Ho+WX+yeRC4SUttuGBx6IQ3zL2tFJ2uW8dDsowKLKXqz+aHPdfScy1csmCDMHBnGpF3LXEIB2lV5rQ0Ccq/Ymq8LqlC/qVVq0CVUZaXP1rKNYiIja17Vyj6fjdp8CL3fQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hJlfgb8/; 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="hJlfgb8/" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 12B59C2BCF5; Mon, 4 May 2026 15:51:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909889; bh=UuCZFcJnawl6nLf6W20Xv9a5MwXy3NjFTm5AuWY4wyg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hJlfgb8/l5VBqYzpfZIMmXaSRwHsc34XGhbfbmPHuNSaxl3dog4Wj8AU/7k0v4R38 H5YUteG3JykwyHvxSGfaNTfsqtBx7RtZi4qAjTTU5VZu9ynOuhx02hEha8fW7X8pxW yhs7z2izyF70XWmEV8toTkUl8yYOfKEXOs275alnRQI1n5bU9flUvwxPvYlxfymUwP rbvquwF6diUhUmhcwCjd6IYmF7TJ3G9Su/vlkbGFM7D35mfIwBUDzGICYsQGDLMl21 x931avm0N7mxQFXyYR1iQGO+vnkmBVfpgAk+jOhYQO1pkxx3KoAbg39uvxTHwFmlAn CiNrbVe4ZcHIA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZv-0000000EyAZ-185n; Mon, 04 May 2026 17:51:27 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Shuah Khan Subject: [PATCH 5/9] docs: maintainers_include.py: clean most SPHINXDIRS=process warnings Date: Mon, 4 May 2026 17:51:14 +0200 Message-ID: X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab building docs with SPHINXDIRS=3Dprocess is too noisy, as it generates lots of undefined refs. Fixing it is easy: just let linkify generate html URLs for the broken links when SPHINXDIRS is used. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 4fc894b377e6..1d7d441e281c 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -104,10 +104,27 @@ class MaintainersParser: =20 def linkify(self, text): """Linkify all non-wildcard refs to ReST files in Documentation/""" + m =3D self.re_doc.search(text) if m: - # maintainers.rst is in a subdirectory, so include "../". - text =3D self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.= group(2)), text) + fname =3D m.group(1) + name =3D m.group(2) + ename =3D "/" + name + + entry =3D os.path.relpath(self.base_dir + ename, self.app_dir) + full_name =3D os.path.join(self.base_dir, fname) + path =3D os.path.relpath(full_name, self.app_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 path.startswith("../"): + html =3D KERNELDOC_URL + m.group(2) + ".html" + text =3D self.re_doc.sub(f'`{name} <{html}>_`', text) + else: + text =3D self.re_doc.sub(f':doc:`{name} <{entry}>`', text) =20 return text =20 --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 A6DEE3E1D12; Mon, 4 May 2026 15:51:29 +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=1777909889; cv=none; b=RTABZ5sNOqRmGFC/RmlOniLPJb3UKVPCxztWKszRksb93gL7jI2eLGx7yMTpYpT7sN5SQTv5YMSYbUQMC4/TqDyr2mcbQU+ei7nPoMoKlf4KCFy7pz0HgG5worr3dd/1oJRWfnVYkcUWqhUzG0PhBXsRs1Cl5NExCGlzWHBGF0E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909889; c=relaxed/simple; bh=gGS+Sq20I0mOflr7aaM6CTdnP+p8jMyJW95cC7Ufmis=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ZCNbb4atwDInWQS5WNAFdq8VRGg1CSGrSOWpAKCh2TShtDdPP5B2AMBvviPu+pbMXusaMSjYWxsJpG0J6qyE2fPKdFc7vF6A1WgmQ5gC2TOZd2fN29ueQhLbEC63ac2Tluqub2fFgCB7ovhLQmHBomM0Koot4PwKiC42JF9IoDw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Uq6GxmTf; 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="Uq6GxmTf" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 56526C32786; Mon, 4 May 2026 15:51:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909889; bh=gGS+Sq20I0mOflr7aaM6CTdnP+p8jMyJW95cC7Ufmis=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Uq6GxmTfIE0M6h1D2DB6OyYiCfP23DmvoYplO1+xsjP7JqJHVAoHTw5SWHhGsDW5q rmUiVXdXP8nmsfvy10yNLyZ00etzL69HlK1eS813T86uBlrL7vbaXJ6xfmUgMp7zR/ Tbj0ycv1LN+5gClVj3D2ObC/hVmaXF45tVBtDF5y0j/+jQAKtRm+9ztyhvXmQtQkOM MVYXdGqPcSo6jfawD23V9fgAfYEWB9cSoGh259fe2sfn+8FzMi0DiE4FyV0eDPSytS ujsHf+rnH1HIGaE8k5+LTqzDJOAgvaqm8h/TZUJ/WFhuOBDFAnY6cA+2USuEiVz4Gu nGFJjnlmulMOA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZv-0000000EyBl-1rWQ; Mon, 04 May 2026 17:51:27 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Shuah Khan Subject: [PATCH 6/9] docs: maintainers_include: do some coding style cleanups Date: Mon, 4 May 2026 17:51:15 +0200 Message-ID: <477be28411d10879596e5864a95e1d495e6ad20d.1777908711.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab Minor coding style adjustments to use the style most python doc scripts are following. No functional changes. Assisted-by: pylint, black Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 101 ++++++++++---------- 1 file changed, 51 insertions(+), 50 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 1d7d441e281c..189f22e5fae4 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -1,30 +1,25 @@ #!/usr/bin/env python # SPDX-License-Identifier: GPL-2.0 # -*- coding: utf-8; mode: python -*- -# pylint: disable=3DR0903, C0330, R0914, R0912, E0401 +# pylint: disable=3DC0209, C0301, E0401, R0022, R0902, R0903, R0912, R0914 =20 """ - maintainers-include - ~~~~~~~~~~~~~~~~~~~ +Implementation of the ``maintainers-include`` reST-directive. =20 - Implementation of the ``maintainers-include`` reST-directive. +:copyright: Copyright (C) 2019 Kees Cook +:license: GPL Version 2, June 1991 see linux/COPYING for details. =20 - :copyright: Copyright (C) 2019 Kees Cook - :license: GPL Version 2, June 1991 see linux/COPYING for details. - - The ``maintainers-include`` reST-directive performs extensive parsing - specific to the Linux kernel's standard "MAINTAINERS" file, in an - effort to avoid needing to heavily mark up the original plain text. +The ``maintainers-include`` reST-directive performs extensive parsing +specific to the Linux kernel's standard "MAINTAINERS" file, in an +effort to avoid needing to heavily mark up the original plain text. """ =20 -import sys -import re import os.path +import re =20 from glob import glob =20 from docutils import statemachine -from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include =20 # @@ -32,12 +27,14 @@ from docutils.parsers.rst.directives.misc import Include # KERNELDOC_URL =3D "https://docs.kernel.org/" =20 -def ErrorString(exc): # Shamelessly stolen from docutils - return f'{exc.__class__.__name}: {exc}' +__version__ =3D "1.0" =20 -__version__ =3D '1.0' +maint_parser =3D None # pylint: disable=3DC0103 =20 -maint_parser =3D None + +# Shamelessly stolen from docutils +def ErrorString(exc): # pylint: disable=3DC0103, C0116 + return f"{exc.__class__.__name}: {exc}" # pylint: disable=3DW0212 =20 class MaintainersParser: """Parse MAINTAINERS file(s) content""" @@ -52,7 +49,7 @@ class MaintainersParser: =20 # Field letter to field name mapping. self.field_letter =3D None - self.fields =3D dict() + self.fields =3D {} =20 self.field_prev =3D "" self.field_content =3D "" @@ -71,29 +68,30 @@ class MaintainersParser: self.output =3D ".. _maintainers:\n\n" =20 prev =3D None - for line in open(path): - if self.descriptions: - self.parse_descriptions(line) - elif self.maintainers and not self.subsystems: - if re.search('^[A-Z0-9]', line): - self.subsystems =3D True + with open(path, "r", encoding=3D"utf-8") as fp: + for line in fp: + if self.descriptions: + self.parse_descriptions(line) + elif self.maintainers and not self.subsystems: + if re.search('^[A-Z0-9]', line): + self.subsystems =3D True + self.parse_subsystems(line) + else: + self.output +=3D line + elif self.subsystems: self.parse_subsystems(line) else: self.output +=3D line - elif self.subsystems: - self.parse_subsystems(line) - else: - self.output +=3D line =20 - # Update the state machine when we find heading separators. - if line.startswith('----------'): - if prev.startswith('Descriptions'): - self.descriptions =3D True - if prev.startswith('Maintainers'): - self.maintainers =3D True + # Update the state machine when we find heading separators. + if line.startswith("----------"): + if prev.startswith("Descriptions"): + self.descriptions =3D True + if prev.startswith("Maintainers"): + self.maintainers =3D True =20 - # Retain previous line for state machine transitions. - prev =3D line + # Retain previous line for state machine transitions. + prev =3D line =20 # Flush pending field contents. if self.field_content: @@ -132,7 +130,7 @@ class MaintainersParser: """Handle contents of the descriptions section.""" =20 # Have we reached the end of the preformatted Descriptions text? - if line.startswith('Maintainers'): + if line.startswith("Maintainers"): self.descriptions =3D False self.output +=3D "\n" + line return @@ -185,7 +183,7 @@ class MaintainersParser: # Render a subsystem field as: # :Field: entry # entry... - field, details =3D line.split(':', 1) + field, details =3D line.split(":", 1) details =3D details.strip() =20 # @@ -246,12 +244,11 @@ class MaintainersParser: =20 class MaintainersInclude(Include): """MaintainersInclude (``maintainers-include``) directive""" + required_arguments =3D 0 =20 def emit(self): """Parse all the MAINTAINERS lines into ReST for human-readability= """ - global maint_parser - path =3D maint_parser.path output =3D maint_parser.output =20 @@ -267,20 +264,21 @@ class MaintainersInclude(Include): raise self.warning('"%s" directive disabled.' % self.name) =20 try: - lines =3D self.emit() + self.emit() except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) =20 return [] =20 + class MaintainersProfile(Include): + """Generate a list with all maintainer's profiles""" + required_arguments =3D 0 =20 def emit(self): """Parse all the MAINTAINERS lines looking for profile entries""" - global maint_parser - path =3D maint_parser.path =20 # @@ -317,15 +315,17 @@ class MaintainersProfile(Include): raise self.warning('"%s" directive disabled.' % self.name) =20 try: - lines =3D self.emit() + self.emit() except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) =20 return [] =20 + def setup(app): - global maint_parser + """Setup Sphinx exension""" + global maint_parser # pylint: disable=3DW0603 =20 # # NOTE: we're using os.fspath() here because of a Sphinx warning: @@ -339,8 +339,9 @@ def setup(app): =20 app.add_directive("maintainers-include", MaintainersInclude) app.add_directive("maintainers-profile-toc", MaintainersProfile) - return dict( - version =3D __version__, - parallel_read_safe =3D True, - parallel_write_safe =3D True - ) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 D54C23E2754; Mon, 4 May 2026 15:51:29 +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=1777909889; cv=none; b=XBulXDPN16q0B6+f8OG9cEb8oOkXfvyyBMRT3sXMLE2/NVaIKx7iljVveoueZQxrTQ3JzJcqiuaksaUdjean9WBNxY5Q0+TeNzcuOTvAZPYUyhhz7H4oce85e/kkKYJHbPxCRAe9kFvfIcDYiI10LhRsOEGcmYoWAtmVYI6gRZE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909889; c=relaxed/simple; bh=bBEz42S1x27nT6zHZwr/ykJ083aYhHNYLcxNYqgBQBA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=phnxyl/G003j2w3xO43plxuEkDx3amHSs3p7DmcFkUcMvOhOwWGWd1c2BtSF6ePQn5S6iqv/yole+zOVjImioST5KpGhjJGLZ2oyJ1hsFlQq2/CrfGnu/5uJt1+zk5t/ImP2GqSazGQhqox9f+1ahWRAOPaUDWrO/D7M7Be+7V4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nQEexr5n; 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="nQEexr5n" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6B5BAC2BD00; Mon, 4 May 2026 15:51:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909889; bh=bBEz42S1x27nT6zHZwr/ykJ083aYhHNYLcxNYqgBQBA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nQEexr5nZSX9L+eemkGfOprKrMqQNPwFar9O41xWDw8/vWoiNwkU6I+SwtwbmsTOq 6wXEa0x6Oyj+tWUXmrRfIPW6TOS0E2bQUx6X3O/h7V1ZMPbCD6jw30Q/hpoRQyxqyZ QE/z+bO/tKNbOc2ACfyyRmeboKTUgBfYJz9sIImSrg6aWON3I2HhZxDs6PIBcy0WJR KWa42JL0vNMQL5CQaYSZnCcNVJehk0HobFkOBIIstKr2JGHQbJDQqVh8AUu9U1hIjw 5pJMDoFrxtSk8oPkQpkF+yjfryfo4eSAInbSjFC2rxR0mSAFCUYFl2DSS4DIfj7Bi/ av/J7w6HIDbfw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZv-0000000EyCw-2aJ0; Mon, 04 May 2026 17:51:27 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Shuah Khan Subject: [PATCH 7/9] docs: maintainers_include: store maintainers entries on a dict Date: Mon, 4 May 2026 17:51:16 +0200 Message-ID: X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab Instead of creating just a big output data, store entries inside a dictionary. Doing that simplifies the parser a little bit and make the code clearer. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 82 +++++++++------------ 1 file changed, 35 insertions(+), 47 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 189f22e5fae4..50359b125db0 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -49,10 +49,7 @@ class MaintainersParser: =20 # Field letter to field name mapping. self.field_letter =3D None - self.fields =3D {} =20 - self.field_prev =3D "" - self.field_content =3D "" self.subsystem_name =3D None =20 self.app_dir =3D app_dir @@ -65,7 +62,9 @@ class MaintainersParser: # self.profile_toc =3D set() self.profile_entries =3D {} - self.output =3D ".. _maintainers:\n\n" + self.header =3D ".. _maintainers:\n\n" + self.maint_entries =3D {} + self.fields =3D {} =20 prev =3D None with open(path, "r", encoding=3D"utf-8") as fp: @@ -77,11 +76,11 @@ class MaintainersParser: self.subsystems =3D True self.parse_subsystems(line) else: - self.output +=3D line + self.header +=3D line elif self.subsystems: self.parse_subsystems(line) else: - self.output +=3D line + self.header +=3D line =20 # Update the state machine when we find heading separators. if line.startswith("----------"): @@ -93,13 +92,6 @@ class MaintainersParser: # Retain previous line for state machine transitions. prev =3D line =20 - # Flush pending field contents. - if self.field_content: - self.output +=3D self.field_content + "\n\n" - - self.output =3D self.output.rstrip() - - def linkify(self, text): """Linkify all non-wildcard refs to ReST files in Documentation/""" =20 @@ -132,12 +124,12 @@ class MaintainersParser: # Have we reached the end of the preformatted Descriptions text? if line.startswith("Maintainers"): self.descriptions =3D False - self.output +=3D "\n" + line + self.header +=3D "\n" + line return =20 # Escape the escapes in preformatted text. line =3D self.linkify(line).replace("\\", "\\\\").replace("**", "\= \**") - self.output +=3D "| " + line + self.header +=3D "| " + line =20 # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName @@ -160,24 +152,8 @@ class MaintainersParser: if not line: return =20 - # Subsystem fields are batched into "field_content" if line[1] !=3D ':': - line =3D self.linkify(line) - - # Render a subsystem entry as: - # SUBSYSTEM NAME - # ~~~~~~~~~~~~~~ - # Flush pending field content. - self.output +=3D self.field_content + "\n\n" - self.field_content =3D "" - - self.subsystem_name =3D line.title() - - # Collapse whitespace in subsystem name. - heading =3D re.sub(r"\s+", " ", line) - self.output +=3D "%s\n%s" % (heading, "~" * len(heading)) + "\= n" - self.field_prev =3D "" - + self.subsystem_name =3D re.sub(r"\s+", " ", self.linkify(line)) return =20 # Render a subsystem field as: @@ -192,20 +168,22 @@ class MaintainersParser: if field =3D=3D "P": match =3D self.re_doc.match(details) if match: - name =3D "".join(match.groups()) - entry =3D os.path.relpath(self.base_dir + name, self.app_d= ir) + fname =3D match.group(1) + ename =3D "/" + match.group(2) =20 - full_name =3D os.path.join(self.base_dir, name) + entry =3D os.path.relpath(self.base_dir + ename, self.app_= dir) + full_name =3D os.path.join(self.base_dir, fname) path =3D os.path.relpath(full_name, self.app_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 path.startswith("../"): - entry =3D KERNELDOC_URL + "/" + match.group(2) + ".htm= l" + entry =3D KERNELDOC_URL + fname + ".html" else: - entry =3D "/" + entry + entry =3D ename =20 if "*" in entry: for e in glob(entry): @@ -222,23 +200,23 @@ class MaintainersParser: =20 details =3D self.linkify(details) =20 + # # Mark paths (and regexes) as literal text for improved # readability and to escape any escapes. + # if field in ['F', 'N', 'X', 'K']: # But only if not already marked :) if not ':doc:' in details: details =3D '``%s``' % (details) =20 - # Comma separate email field continuations. - if field =3D=3D self.field_prev and self.field_prev in ['M', 'R', = 'L']: - self.field_content =3D self.field_content + "," + if self.subsystem_name not in self.maint_entries: + self.maint_entries[self.subsystem_name] =3D {} + + if field not in self.maint_entries[self.subsystem_name]: + self.maint_entries[self.subsystem_name][field] =3D [] + + self.maint_entries[self.subsystem_name][field].append(details) =20 - # Do not repeat field names, so that field entries - # will be collapsed together. - if field !=3D self.field_prev: - self.output +=3D self.field_content + "\n\n" - self.field_content =3D ":%s:" % (self.fields.get(field, field)) - self.field_content =3D self.field_content + "\n\t%s" % (details) self.field_prev =3D field =20 =20 @@ -250,7 +228,15 @@ class MaintainersInclude(Include): def emit(self): """Parse all the MAINTAINERS lines into ReST for human-readability= """ path =3D maint_parser.path - output =3D maint_parser.output + output =3D maint_parser.header + + for name, fields in maint_parser.maint_entries.items(): + output +=3D "\n" + name + "\n" + output +=3D "~" * len(name) + "\n" + + for field, lines in fields.items(): + field_name =3D maint_parser.fields.get(field, field) + output +=3D f":{field_name}:\n\t" + ",\n\t".join(lines) + = "\n\n" =20 # For debugging the pre-rendered results... print(output, file=3Dopen("/tmp/MAINTAINERS.rst", "w")) @@ -286,6 +272,8 @@ class MaintainersProfile(Include): # output =3D "" for profile, entry in sorted(maint_parser.profile_entries.items()): + profile =3D profile.title() + if entry.startswith("http"): output +=3D f"- `{profile} <{entry}>`_\n" else: --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 D1D123E2751; Mon, 4 May 2026 15:51:29 +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=1777909889; cv=none; b=gHhIE0EnQN/ToFAzNKHYeIvYfp5tRrSnw8kQH86E0txo3OW3bUCfbSh0NaiS5lzR9xS65rlMtUa4fVXpTkrXa/8MZNBqjlcZsjN73MkMRb5Oxk9P/3EMJgkXjeV7waNWHB+y2av0mRbJ+i8n/PBgFB1m1rCsLx86mTzJif7QOA4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909889; c=relaxed/simple; bh=OEd0+YSd1pN5VoGvQ/n7JNcZR0hP8+/xnr6xw2USiE8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dD2d6P/9h5jEy/ce2jyrAYuYv0/xU+teiQ5U0eWXk2LiyTzrNYHriaWyVA7o7lMhXi3PNPPW7LHDGUcEUvbapEiO8Xt++4Us2ou8g/PLU2CZWB/hY1ZZkSWmT8Ow1RbKRf9177Mc/Uncwr8nuCiqXXtdOAqiZEwvn1+RBoXDvUw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Sg57eCot; 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="Sg57eCot" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 89D5DC4AF09; Mon, 4 May 2026 15:51:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909889; bh=OEd0+YSd1pN5VoGvQ/n7JNcZR0hP8+/xnr6xw2USiE8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Sg57eCot01ZLChJqbjVpoUAx92w/zRFOxNOcirL1v6iav2txuPjuEcpV16h3gOUkz FjqlxhcpiB5IrZeoAELx1n/Zv8+b2ZRAV456ezJwH+V1Ylp9xMGY7zlJNF4vCLHkkn 6aOrnkSlj5/NAg2FTTSU9n4OPjrClFp839lIsh6Ji2ezYGqnxRQczop9Gy+mWy4bfc VEKOFdigFTDuVRyVh4MliXtC127PpzM1ef/mC9BUhz+fhoN3GpdC4/xquSz4Fy7wqd z+B/bH+ku5FcHZq2WoOMRJmb72cUSO3kessWuBqfmhmbiprpbNQhp9bAerf5zK+j7B gh0prL4yMCPlA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZv-0000000EyE7-3JAH; Mon, 04 May 2026 17:51:27 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= , Alice Ryhl , Andreas Hindborg , Benno Lossin , Boqun Feng , Danilo Krummrich , Gary Guo , Miguel Ojeda , Shuah Khan , Trevor Gross Subject: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries Date: Mon, 4 May 2026 17:51:17 +0200 Message-ID: X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab Currently, there is a "P" entry for Rust pin-point that is neither a valid ReST file nor an hyperlink. While the real fix there would be to ensure that the documentation can be properly seen at documentation, add a logic to handle it as a file. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 50359b125db0..bbdadf2aa4f3 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -197,6 +197,8 @@ class MaintainersParser: if match: entry =3D match.group(1).strip() self.profile_entries[self.subsystem_name] =3D entry + else: + self.profile_entries[self.subsystem_name] =3D f"``{det= ails}``" =20 details =3D self.linkify(details) =20 @@ -276,6 +278,8 @@ class MaintainersProfile(Include): =20 if entry.startswith("http"): output +=3D f"- `{profile} <{entry}>`_\n" + elif entry.startswith("`"): + output +=3D f"- {profile}: {entry}\n" else: output +=3D f"- :doc:`{profile} <{entry}>`\n" =20 --=20 2.54.0 From nobody Sun Jun 14 02:31:57 2026 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 3B2C83E3C48; Mon, 4 May 2026 15:51:30 +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=1777909890; cv=none; b=W9IiHzIAp0B9ygS/Li8sJgxktA1shylACu84o+pThUlMoass00Guqvs2n9EXt5/nyHwRzfi+xqpIYoI4Fhckd+aqiRtaOyW9bnOinWE3Njc3jd7l3fbbXEywZdudca9SAAwiQtbUn8aybsjGs6E264yUPcItSYPjodJGOAPbcWM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777909890; c=relaxed/simple; bh=NgkZooe3CB6Mf13tkY5wF+JWazebe4oFO2B6aSDF0ac=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=l2mThKqQff8R/gbOWPhZ68fGPo084q8CUAVwfyaMx2sJ5KMXkqGzOgXm72+DCO/TQlZM6EVF7vYtXTqwBEMpn14Vrqs3lSXf2GqRjv2NKS32eaxIrH9MctLg9xXLsAW5B4OD3M6ygyGfZeYr3vZRwb1mFEV740e/xOL4pjZ87Zo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sLz4O8fQ; 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="sLz4O8fQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D86FAC2BCB8; Mon, 4 May 2026 15:51:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777909889; bh=NgkZooe3CB6Mf13tkY5wF+JWazebe4oFO2B6aSDF0ac=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sLz4O8fQkgNLMdM28+PuhOQanBqjVtECLrWGPGhQRU5l5BKcs6MCluTwPoOghXfAf FpbB7Y1zCBkRaRTfPcoy8zvUO70aZS6lKDfLgMAGAePs76yHaBxMuYmDP2hl9whJR2 CVG08QZGyRbS75i5IEdUlMKsljFw4Gv0XEn7BU5bQw7l7SwHiofr5/ghemoMbbcmY5 vdheRRMq30R1cP50pcDe9jvty5xQTVFVdz2vnLyY8v3+EH1HuS//GmXiBMgOEvSfzA EdArUZePOZ9Qoyfdp/sj44mAXFl3EkG695Wj7UKX2M3SK+aazGt5lilsIB++GyjbDK 29D+cIx5ejlVg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wJvZv-0000000EyFI-41NG; Mon, 04 May 2026 17:51:27 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, Shuah Khan Subject: [PATCH 9/9] docs: maintainers: add a filtering javascript Date: Mon, 4 May 2026 17:51:18 +0200 Message-ID: <854faf4127053c203cae479f68e6ac12a4e4aabc.1777908711.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.54.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: quoted-printable Sender: Mauro Carvalho Chehab The maintainers table is big. Add a javascript to allow filtering it. Such script is only added at the page which contains the maintainers-include tag. I opted to keep the search case-sensitive, as, this way, upper case searches at subsystem. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 77 +++++++++++++++++++-- 1 file changed, 71 insertions(+), 6 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index bbdadf2aa4f3..f85298627da2 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -31,6 +31,48 @@ __version__ =3D "1.0" =20 maint_parser =3D None # pylint: disable=3DC0103 =20 +JS_FILTER =3D """ +(function() { + function filterTable(table) { + const filter =3D document.getElementById("filter-table").value.trim(); + const rows =3D table.querySelectorAll("tbody tr"); + for (let i =3D 0; i < rows.length; i++) { + const tds =3D rows[i].getElementsByTagName("td"); + let match =3D false; + for (let j =3D 0; j < tds.length; j++) { + const cellText =3D (tds[j].textContent || tds[j].innerText); + if (cellText.includes(filter)) { + match =3D true; + break; + } + } + rows[i].style.display =3D match ? "table-row" : "none"; + } + } + function addInput() { + const table =3D document.getElementById("maintainers-table"); + if (!table) return; + let input =3D document.getElementById("filter-table"); + if (!input) { + const filt_div =3D document.createElement('div'); + filt_div.innerHTML =3D ` +

Filter: + +

+ `; + table.parentNode.insertBefore(filt_div, table); + const input =3D document.getElementById("filter-table") + input.addEventListener('input', () =3D> filterTable(table)); + } + } + if (document.readyState =3D=3D=3D 'loading') { + document.addEventListener('DOMContentLoaded', addInput); + } else { + addInput(); + } +})(); +""" + =20 # Shamelessly stolen from docutils def ErrorString(exc): # pylint: disable=3DC0103, C0116 @@ -62,7 +104,7 @@ class MaintainersParser: # self.profile_toc =3D set() self.profile_entries =3D {} - self.header =3D ".. _maintainers:\n\n" + self.header =3D "" self.maint_entries =3D {} self.fields =3D {} =20 @@ -230,15 +272,28 @@ class MaintainersInclude(Include): def emit(self): """Parse all the MAINTAINERS lines into ReST for human-readability= """ path =3D maint_parser.path - output =3D maint_parser.header + output =3D ".. _maintainers:\n\n" + output +=3D maint_parser.header + + output +=3D ".. _maintainers_table:\n\n" + output +=3D ".. flat-table::\n" + output +=3D " :header-rows: 1\n\n" + output +=3D " * - Subsystem\n" + output +=3D " - Properties\n\n" + + self.state.document['maintainers_included'] =3D True =20 for name, fields in maint_parser.maint_entries.items(): - output +=3D "\n" + name + "\n" - output +=3D "~" * len(name) + "\n" - + output +=3D f" * - {name}\n" + tag =3D "-" for field, lines in fields.items(): field_name =3D maint_parser.fields.get(field, field) - output +=3D f":{field_name}:\n\t" + ",\n\t".join(lines) + = "\n\n" + + output +=3D f" {tag} :{field_name}:\n " + output +=3D ",\n ".join(lines) + "\n" + tag =3D " " + + output +=3D "\n" =20 # For debugging the pre-rendered results... print(output, file=3Dopen("/tmp/MAINTAINERS.rst", "w")) @@ -315,6 +370,14 @@ class MaintainersProfile(Include): return [] =20 =20 +# pylint: disable=3DW0613 +def add_filter_script(app, pagename, templatename, context, doctree): + """Add Filter javascript only to maintainers page""" + + if doctree and doctree.get('maintainers_included'): + app.add_js_file(None, body=3DJS_FILTER) + + def setup(app): """Setup Sphinx exension""" global maint_parser # pylint: disable=3DW0603 @@ -332,6 +395,8 @@ def setup(app): app.add_directive("maintainers-include", MaintainersInclude) app.add_directive("maintainers-profile-toc", MaintainersProfile) =20 + app.connect("html-page-context", add_filter_script) + return { "version": __version__, "parallel_read_safe": True, --=20 2.54.0