From nobody Sat Jun 13 20:55:25 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 E6E993E8C5D; Tue, 5 May 2026 13:26:04 +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=1777987565; cv=none; b=nffweJYK6PVZuqsg5aTR46PGFsD0c2rw8BIRgL8P6KU5UBjcgq1ERg29EYn/gcXLTXS0i2doIPLX0zN7fx8Rpnoh7BegSTMVj1a7ETzC3NSae8O7kCanYR6VpLI9wkW5L9IM+NwB74t8HYEaXouOAZh0KnXgP0t+6vNLciA5b4s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=2rCh0cm5RWMg9+ON81fn8pbk1MPx1pRqHPKriNZbsTw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Owl8g7r6RlJgKu0niPvb4QlAqxrjVtBd6wJWfc2qWWflcIQWn+/ilN9DqNWbZhY3GXGNtaQEbrbStf2VeOX9KuwAgYI6PdqUEfQSws43txojFD+Df4F6MXpK9ohJzGMivb5YNQNEg0btwsd3OYb0Vg85okRE6QEeEJkZXfCfsDk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=SK4T6LlN; 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="SK4T6LlN" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7BD50C2BCB4; Tue, 5 May 2026 13:26:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987564; bh=2rCh0cm5RWMg9+ON81fn8pbk1MPx1pRqHPKriNZbsTw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SK4T6LlNaB+w5YFGd/oEcCVU8377bM8Q1F8a+ebVIQ0dQP3M4g1pj6rRgtQ4HTeXr K+3UxO4Omte6C7dN8rIbb3DQ0W08NYOPXYr/43AnWiE57kEib+mtsRzan+9K7CyaPA kw6fhN33fYCL4inDcWPoeBOnRPyTXoh2I0YlaRVViDRTwb1PhRVp3CHDZSDqmDQg55 gPA53w05Q2HFYJhZvwNczHO+88HuVfsCJ9LcquywK2xoNvi7EEcIhy103DjR+050UA Jc7w03QaDFVyG6EDuNek2WgbhCbY4ASBgj3pT7hFrsZ3C4tU4yO3pRlc3bsTiVogku 0lxe5gjxlxJkQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFmk-00000004idJ-3IPB; Tue, 05 May 2026 15:26:02 +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 v2 01/11] docs: maintainers_include: keep hidden TOC sorted Date: Tue, 5 May 2026 15:25:48 +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 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 436e7ac42ffc..694cdbdc4caf 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 Sat Jun 13 20:55:25 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 5958644BCA5; Tue, 5 May 2026 13:26:05 +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=1777987565; cv=none; b=SpdBC874zL3HaXMTNQ2cmkAXYsJBvJ8+tfj6lhHnBPOq0fHtL0dt4iR8zm0VZ/FM8eBLr0gqKCBK51dVPXknAIAm3OxOn+wc3cX0AFiUHPkplAjM7SYTD+KmKds3DAWGA5E93GrzHsaKXqzd2c8xOGz3S448hyBKcusD0s8RIrE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=IZImVP8c+ey+xlWh+v0vjXYkjWCH8nfwkViflJwfEr4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DseIWQhkeYpPX6KPksFBvSQeVkb3MZzTpZEIFHDFoM31LA8RVhTeeByi+gDyopQ2aaR34IiWgOWIhmDLJeIa2AywNJ8hYJcUc1GqzicL4bbd5OheLocT+yDhB8QFu44j+nI8fnvp10Gfh5x8+F9vTiP61VHu7FsfG7FjlRevYO8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rg0enokE; 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="rg0enokE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CFB39C2BCC9; Tue, 5 May 2026 13:26:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=IZImVP8c+ey+xlWh+v0vjXYkjWCH8nfwkViflJwfEr4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rg0enokEVv2NmJ+CTkhvhteYZQueTToh8a8YAX77qnSGUtz/UcKd/1v+iaBludaEa duTefMawUmBYAHMhG19Saaor6a9cNHwENSH+cO6RIVSGKtpDtRhKwWPBVaJSUH+1jB HDM8DnD6feImlygWhqU+akEXG4jjtbO2e2gVKvwjj3h9C0e5CIU5TSVzr8Y2idi5Qx LPz/mi93fkQ+l601kBharpm4wAEwxkW2iFiUw7DMyylIjCNN8JEf3L7wiNTxjmUXAQ 4BPd93gV6inxbTXQ0BE+l6nJ4IyLI4H/RseNsBuc/0qh9Zdu+IW54cbocRXj9UOA5S rI8okPmr3zykQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFmk-00000004ieo-3zzc; Tue, 05 May 2026 15:26:02 +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 v2 02/11] docs: maintainers_include: split state machine on multiple funcs Date: Tue, 5 May 2026 15:25:49 +0200 Message-ID: <0b72530cf496ce5e2987ca784058a50f4dc814d2.1777987027.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 | 297 +++++++++++--------- 1 file changed, 158 insertions(+), 139 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 694cdbdc4caf..6d47d55f5b73 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -47,167 +47,186 @@ 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("\\", "\\\\")) - # 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("\\", "\\\\")) + + # 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 Sat Jun 13 20:55:25 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 591B5449EB6; Tue, 5 May 2026 13:26:05 +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=1777987565; cv=none; b=f6tgtKipYFi63uyk0fNXkdKrRK+l7jqgTzfaGaNel73wdztjoPB7+t4/H4MxhW3g2X+WhT1+fXTp2c7WN2Jr9uliEFA5k0W6n4EFDrmecGfySxZHFCeg9OxG61nFN4cCZfaYb9XWlS6kEnj5r1YgflG4uQFGH9GEIQOtIgEyHXI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=BRgrkljmlnsHXNl7xMo4stUL0yj0QEZrVgevBBmzCys=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=AUAmV1Q9F7WvdP1zcHkmOVq+LZgQkus1sfLSCmG+Ezurh0K0y/QgtgAOt8VZud5r8ZoykPywfLtnHXHWsaaXxegrpNCmz9PyKSCmzNb9F04ooAevjAYYphX82U8lrEuUXYADqHSmJoN19/IHOVJsI7MyErPef92eLmqKvcVhZDM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=E8gO/3S0; 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="E8gO/3S0" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D8879C2BCF4; Tue, 5 May 2026 13:26:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=BRgrkljmlnsHXNl7xMo4stUL0yj0QEZrVgevBBmzCys=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=E8gO/3S0riv6BvFYCgzEDR4A90aKVyqiNFV80wNMpgp/zayWgK8w7mom/TWZaKv19 MUUvcLibeAlQ4/5u+O+Aau+TqXVjVfigRtZ7psBgDwjNAm32Uu+i24ZQbMWVwNGIw3 XnJdQAk+fF6rUMk7kvRbnF69pkcWVkwbQDMeyuadpXkwnLBEiYXMO4112fXs5G1oEu l7BOeh/Nzd9xwh2UjE3EhhbhlIH0o9FYgxv4DZRwbRpzX+RR3LaRsieCoCW9B7F8QM r4Ve/GGG09H3zQUsUWKKJqm113qaDN7l5WCaLbl6I83FAvOHhuB3d/VTeEHs0SpXNa dDk8NSDm5uRlg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFml-00000004ifz-0W8l; Tue, 05 May 2026 15:26:03 +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 v2 03/11] docs: maintainers_include: cleanup the code Date: Tue, 5 May 2026 15:25:50 +0200 Message-ID: <24a83995778de8710cac40a3089c2f2fe5c38dbd.1777987027.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 Simplify the logic without affecting the output result. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 184 ++++++++++---------- 1 file changed, 91 insertions(+), 93 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 6d47d55f5b73..615af227a8f8 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,14 +120,8 @@ 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("\\", "\\\\")) + self.output +=3D "| " + self.linkify(line).replace("\\", "\\\\") =20 # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName @@ -127,105 +134,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 Sat Jun 13 20:55:25 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 592A344BC93; Tue, 5 May 2026 13:26:05 +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=1777987565; cv=none; b=H1gJWUXT0OZ0qZngKN/PDVi5Kgph3NZ/zJ2pYW+rdS1JtaX7NMGrSkPT3+I9AEDYpZ9tNlNQ5v2AOuftFc9d4regeGGygC/JdFJBRE57kwQ4lrxlCGqS0t2x9DWVAlN7OLVbjPCBeDt6MES6Ti94pvK4mMctO2zpFS7ss+snexk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=xX8jdqJe6OyYVBhHmMog5VS+gV1ubfBCDKiP09ArwZE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ldC3rMDydAxto4mhLZvJezsrHM6awrEq0z2I2R9ap9ClJ9TPHR4pIkWj30LKAbYgmpUnqqtTJIHl1ZIlbWxAmEAYLFSoyzUshy39OViv6aWhMPvr3s7O4voFN3wOv6MqmBE4cN/SxB4f8JqFR6jnAQs5F1nOiys/nW+jzA2LYqY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=DI3ZC2I+; 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="DI3ZC2I+" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 255D4C2BCF7; Tue, 5 May 2026 13:26:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=xX8jdqJe6OyYVBhHmMog5VS+gV1ubfBCDKiP09ArwZE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DI3ZC2I+/wkK7PmKhCqwZ/qIcGwtYTu5oyPB8gwPNj2tXDXnX70wH8ScI2HV3ISY3 As1LMteYqI2xTzg9/+6lSWDV95buMZduufUDOA5PNg54jruSVU3nPQrl1aYA7e2xza Nh+wJtVmViBPM5FetIjGj5pcOVjeKWritFyPc7WtduzuX3wV8NXNcGDrKqpTBZb6Db +BbNcoHZpsfV7Cu2g1ALKkWD8bh++JbqMZS8heucz332XOzvD/t05pUCnBerePnMFs bXabPclpCLclcJAYqr0u2Xu8wh9T2l21ibXbo8u94ASPuxqbKqvcK605idaul9K4Wp 0kydC6QDo8Jrw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFml-00000004ihA-1E0p; Tue, 05 May 2026 15:26:03 +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 v2 04/11] docs: maintainers_include: clean most SPHINXDIRS=process warnings Date: Tue, 5 May 2026 15:25:51 +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 | 44 +++++++++++++++------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 615af227a8f8..d3ad01e5309e 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -58,8 +58,8 @@ class MaintainersParser: self.field_content =3D "" self.subsystem_name =3D None =20 - self.app_dir =3D app_dir - self.base_dir, self.doc_dir, self.sphinx_dir =3D app_dir.partition= ("Documentation") + self.app_dir =3D os.path.abspath(app_dir) + self.base_dir, _, self.sphinx_dir =3D self.app_dir.partition("Docu= mentation") =20 self.re_doc =3D re.compile(r'(Documentation/([^\s\?\*]*)\.rst)') =20 @@ -104,10 +104,25 @@ 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) + ename =3D m.group(2) + + entry =3D os.path.relpath(self.base_dir + fname, self.app_dir) + entry =3D entry.removesuffix(".rst") + + # + # 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("../"): + html =3D KERNELDOC_URL + ename + ".html" + text =3D self.re_doc.sub(f'`{ename} <{html}>`_', text) + else: + text =3D self.re_doc.sub(f':doc:`{ename} `', tex= t) =20 return text =20 @@ -176,27 +191,32 @@ 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) - path =3D os.path.relpath(full_name, self.app_dir) + entry =3D os.path.relpath(self.base_dir + fname, self.app_= dir) + entry =3D entry.removesuffix(".rst") # # 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" + + if entry.startswith("../"): + entry =3D KERNELDOC_URL + ename + ".html" else: entry =3D "/" + entry =20 if "*" in entry: for e in glob(entry): - self.profile_toc.add(e) + if "html" not in e: + self.profile_toc.add(e) + self.profile_entries[self.subsystem_name] =3D e else: - self.profile_toc.add(entry) + if "html" not in entry: + self.profile_toc.add(entry) + self.profile_entries[self.subsystem_name] =3D entry else: match =3D re.match(r"(https?://.*)", details) --=20 2.54.0 From nobody Sat Jun 13 20:55:25 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 6D78B4611F4; Tue, 5 May 2026 13:26:05 +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=1777987565; cv=none; b=tem+4sE/GnAx5Ne+Ws1SGPWvtbQ0Nxg1O6GtlB4sF8fUQrylo6/9G6kvOhUewP1S+OXr7FxpqyUf6QH4nHYOwMXSDtIRNACiXuZTU7qsWSPopHpGV5i7hB8zpOD0tPCDeitaGK2iMkbNJDbdNnd2hD1dgcqOEX/y9Qk++2M9dmk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=YvaRCtftfZK5OkZseWD8Of6dwh1Rug3EykgCU5rGahM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=bN9NjSjajvZyoiz/BDNVpnPWLo7qdts46YgbBnYWv3dikhAu7QA6N1B9T4WnfavftBKqbWEobaleWTlhX8ubb3HjZ6zUnAUz3LC45GrsUN1vAsRri1u7Uv/XCshAERjLFQTnRRenqH9Jg0PuDrcM8WcoypPr6G25gvG/re5gFTU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ninsZURr; 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="ninsZURr" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 29540C2BCFA; Tue, 5 May 2026 13:26:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=YvaRCtftfZK5OkZseWD8Of6dwh1Rug3EykgCU5rGahM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ninsZURrTES27F46d8ksrE+BEEmVi7zaSeLOL7N/kfjFjirtZ+jrU88b6I7vwGDwm 8GlUgjfkQ8TNGqiUte6xoFyXOYEv5gp7HU968gqFbm/eZsrtBvTVeN7bMABVu8hIKK AmIeUXWJ13Mb6Vt29xnPiyFzobEu4giJS8OGL7rsDEvF+6/WjyHzTDqikFn2GbWhD4 r1haXhgj4/w6BkWk6Ir1Hckk7HnMzIod3H36NDoqudwma+rHSSMhGjFuY+6irytw0w Zor4Mmtnpzk7J4FiVpE4A1n1Mml68ZqfAhzQ/98XFZklJryy2s/nIjKo8FeNInsX07 xInS8ufw4e8hQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFml-00000004iiL-1wXA; Tue, 05 May 2026 15:26:03 +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 v2 05/11] docs: maintainers_include: do some coding style cleanups Date: Tue, 5 May 2026 15:25:52 +0200 Message-ID: <460aabd0518f080b34e12fdc0beb7ec7685d5866.1777987027.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 d3ad01e5309e..7edda808ef99 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: @@ -130,7 +128,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 @@ -182,7 +180,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 # @@ -248,12 +246,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 @@ -269,20 +266,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 # @@ -316,15 +314,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: @@ -338,8 +338,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 Sat Jun 13 20:55:25 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 A1C9947AF6D; Tue, 5 May 2026 13:26:05 +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=1777987565; cv=none; b=QRfOmY28FZF6IOsWUV9v1zLA6oFj5F9hHjB9K13YdcnqcevQa7jC5aCjfUd8Y6s0MyCD5UEUlLlN4wE+YBBUS//OC2R8Reio8D/XczxNl/ojzeL2z9y2rUo9dGjdx3mp7iiv47vb+IjyHygrZlOCBTRDPgExGPStHV1fLmpHcso= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=IptqQrHqbyc0nBEZle1mPWbIU5s/VAiZYA4tkTTC7ao=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=YD7PfJU7cDVW3l4pNgMqF6FaYIO+e/U4C3gbz3fKqonNSP/JgqTDCjUD0nJFWBhfk2oXh4+dX2YUI+9618s5keeT/4iI0J9C3Zd1iIsiiuZk91umQRqXR/J+xULNAhKL6/8COKfx3PMKrD28DOiPE1wgL3VYDG40OcUK6361mkU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=SOXqcLzv; 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="SOXqcLzv" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 82698C2BD00; Tue, 5 May 2026 13:26:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=IptqQrHqbyc0nBEZle1mPWbIU5s/VAiZYA4tkTTC7ao=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SOXqcLzvZIjeszJjDU9HRqs031oHZ1Ii3RSdQBUYbT7fE4KdptVmO5w/2cbR9Lddt CGdETuKMMfnaGf3xvQStgGnZRrwomZ7LGKnATV3pxxQWtKG8cG4vgGh00qsg53q8VO nNfBzzSefzPYEeDtG3QZlD4qgvLMz+S6m8IsnNvGMENqDbRvcSVaoTzx3xkft5lKo/ LKb8N/+Nd93BDOrfcIs550vJSafMPxCZXiqd7dIGk53b3tfUtKCitAjJ0P6MMWKRAa RDkVBOKz2MrZ0D3ACiXp8W//7ZtHSi7ML8xgfwkR9vo2hi2Wj4LeaScdzzXH2BN3wZ JyG1DxKVO3rsQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFml-00000004ijW-2elL; Tue, 05 May 2026 15:26:03 +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 v2 06/11] docs: maintainers_include: store maintainers entries on a dict Date: Tue, 5 May 2026 15:25:53 +0200 Message-ID: <4ad88179e03436984f29780ae380d50591f86c67.1777987027.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 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 | 70 +++++++++------------ 1 file changed, 28 insertions(+), 42 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 7edda808ef99..6f1bcbde90c4 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 os.path.abspath(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 @@ -130,11 +122,11 @@ 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. - self.output +=3D "| " + self.linkify(line).replace("\\", "\\\\") + self.header +=3D "| " + self.linkify(line).replace("\\", "\\\\") =20 # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName @@ -157,24 +149,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: @@ -224,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 @@ -252,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 sorted(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")) @@ -288,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 Sat Jun 13 20:55:25 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 AA76747CC69; Tue, 5 May 2026 13:26:05 +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=1777987565; cv=none; b=u5ZC3JVoR0dfpdgpLmLRZmpXkS5yIVB6H0TrDeipNbHdPXM4e9i6M2vrFHJ8n55RXJ01UrpOFrrN5loQ/sTl3RKcH0AYN+F/Z9vt15zq6imptep+kkMhEp+zoITEHCDMX6yfPDMcOZhhRph02IfHOFvq+4jeu4fK661xOJnnAKo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=B8kHGAnSuUn7wWL9140Hx26Rq6FQnrbj68SYtjdI2Eo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=s5tT1MsaQICeiAs7HrHofMx2q4wzgQSokCSzBOEk4dk9F06CAdK8QRQqWK248X40nzw8wZYz08T8eXibxmf9g3S/CIDVxZPPi8DrO1mXfHO8OLalP6RH/+XgJEBf4d1asbKkA7eIjPX3VPD2iBgP0R+iBteepHnxkAjWT23Ugjc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=bIauZf8D; 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="bIauZf8D" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 814DAC2BCFC; Tue, 5 May 2026 13:26:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=B8kHGAnSuUn7wWL9140Hx26Rq6FQnrbj68SYtjdI2Eo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bIauZf8DEuj70yvZE9GnxX1vNp8kfZr6jVh2e68zgU/laH8lQCmvYnWstiMcFFiNH Y0a0n894S0PjwQWaG8N1uuRcU4iX8L1XqBEhUz7OLfSB++x5GjsIiXbQF81ZVsylQY CcvCeHQP/OPCSfZ5Gbpg4Aq5cMYkO3UZvqNbLJ84NVVYyj0zHu1xuOb7lb5TTHrh+6 pfZb4gFIaPYg41JP5q980qpvI+50xJ+7diaw+kw5nJMRrCmZ1FOo4hgZJCTgwp4Xgn 7N/7SmB77Ykp+eu6r7Ukfws+S90zakghEXe++wW0pZLik1WPjv8j35TPCZcUSi4wnd hdlC1q2t7h4Ow== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFml-00000004ikh-3N8J; Tue, 05 May 2026 15:26:03 +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 v2 07/11] docs: maintainers_include: properly handle file patterns Date: Tue, 5 May 2026 15:25:54 +0200 Message-ID: <89127706fb3493d00ecb21e528c8a27081e5ed40.1777987027.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 handling asterisks inside file patterns atdescription part is problematic, as ReST has special meaning for them. Due to that, convert such patterns to literal strings. Reported-by: Matteo Croce Fixes: 420849332f9f ("get_maintainer: add ** glob pattern support") Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 26 ++++++++++----------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 6f1bcbde90c4..8916d3512e0d 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -47,9 +47,6 @@ class MaintainersParser: self.maintainers =3D False self.subsystems =3D False =20 - # Field letter to field name mapping. - self.field_letter =3D None - self.subsystem_name =3D None =20 self.app_dir =3D os.path.abspath(app_dir) @@ -125,19 +122,22 @@ class MaintainersParser: self.header +=3D "\n" + line return =20 - # Escape the escapes in preformatted text. - self.header +=3D "| " + self.linkify(line).replace("\\", "\\\\") - # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName - m =3D re.search(r"\s(\S):\s", line) + m =3D re.match(r"\s+(\S):\s+(\S+)", line) if m: - self.field_letter =3D m.group(1) + field =3D m.group(1) + details =3D m.group(2) + + if field not in self.fields: + m =3D re.search(r"\*([^\*]+)\*", line) + if m: + self.fields[field] =3D m.group(1) + elif field in ['F', 'N', 'X', 'K']: + line =3D line.replace(details, f'``{details}``') + + self.header +=3D "| " + self.linkify(line) =20 - 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) =20 def parse_subsystems(self, line): """Handle contents of the per-subsystem sections.""" @@ -206,7 +206,7 @@ class MaintainersParser: # if field in ['F', 'N', 'X', 'K']: # But only if not already marked :) - if not ':doc:' in details: + if ':doc:' not in details and "http" not in details: details =3D '``%s``' % (details) =20 if self.subsystem_name not in self.maint_entries: --=20 2.54.0 From nobody Sat Jun 13 20:55:25 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 D133D47D930; Tue, 5 May 2026 13:26:05 +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=1777987565; cv=none; b=ZU+sRIW2W0YCsMpdUw3528LvGxuaxuqAF6JPQc0GcWGaMIHDJBWfBUBz3k91oFb+CHZycD3xbnbEAdnraalvGRGeh+R8tBRvdUppaXqCRAASF/PzK2QXZDs3FemFuBPne7w0KKMC0UyYSg6KdSZaFAcmuWYVkjrHBEjvhjgb/ZY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987565; c=relaxed/simple; bh=xlOkI4UY8PAm2Hj2oIZ4e62rvRVONV2P++giJ2k/+hA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Kt7Uk5f1A8LXLr4ZipBDHhc0Z1yNOYHSSCm+/ZqcAU1Sl3s0hEa/Fty2W+vh236kRLgq/lzrK12hpHZtTm+fYW6lUlLhLdADjKDNTJ7jBWGmTt/M0FzUKX7HO6n4OwfwkEznmbOOl/tit3YaQR77HfAVQlrsQJFdjUpR1fd1Tik= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Gt6T05Ta; 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="Gt6T05Ta" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AD028C2BCC9; Tue, 5 May 2026 13:26:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=xlOkI4UY8PAm2Hj2oIZ4e62rvRVONV2P++giJ2k/+hA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Gt6T05Tar3mhkUsm5sobZaj30JGUFshA9nYWiVB7j+SKrN8ylNmOnJ0V3lgsVhQy7 MYwuAgGjp8tm7LFKfBhxZd5IiPR3igKNHTqwTQ9G+hnjhtnmdRO5opx/IX5+eR1PIs Hu5aHNr/5xEXPTdfshNJ6RY+knXe0GzMY7NVDebfPcUWaRe6GoldePzzxPwtoZGRL8 P41s02nAtfJg4pXbK7Nf8e2+EuPbGRvzzRqCEr9km+4l1BHatMJY56rKbJmA1PLO8t 41JruwNpzkyMnMGRzcfA8XVTq2AxCQrSXp1cmtpTha/XDnVZnx3PJ02cG+BbvUxZ6W OdtOxQNeNYsQw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFml-00000004ils-45Nk; Tue, 05 May 2026 15:26:03 +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 v2 08/11] docs: maintainers_include: add a filtering javascript Date: Tue, 5 May 2026 15:25:55 +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 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 | 78 +++++++++++++++++++-- 1 file changed, 72 insertions(+), 6 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 8916d3512e0d..572c382db2c2 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -31,6 +31,49 @@ __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: + + subsystem or property (case-sensitive) +

+ `; + 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 @@ -59,7 +102,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 @@ -228,15 +271,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 sorted(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")) @@ -308,6 +364,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 @@ -325,6 +389,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 From nobody Sat Jun 13 20:55:25 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 0E59D47DD55; Tue, 5 May 2026 13:26:06 +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=1777987566; cv=none; b=rU8CKhpHUE5UbyUzJck2Yfe+TERJz9KGyGBR9UuP6ep+QVSDs0wa52jShsznBhsLfn9vF7b4x2OACg/bpCXVrmgYQ5gXaqLco3UbuscVTxwGdnv7xBh6fZtKPH9F5vnuyGBLDyxwqmovU5gzZJTpLDRHb7XszzTkg+bEwMb/p9o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987566; c=relaxed/simple; bh=wC46UUzd9fgig10J2h6Bx3Jb7hV0ovBK6e+2aW5W3SE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=oIlYar5R+lCQ0S6ixctm2qbge4/35S56U/r2OJDEG7AFecEeOweYjdhllLwhJg9OVEIZaR0J/gBXXZ+j0U0BYMYVl20brwALVMStXVwgsBXKVrqKPqSMTg5ZMYFryJyH+ZbtxWnT3upXJRSp44LI7jey1DgcGtmfGHw64MQOB+g= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=jn2gwJJE; 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="jn2gwJJE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DABA4C2BCB9; Tue, 5 May 2026 13:26:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987565; bh=wC46UUzd9fgig10J2h6Bx3Jb7hV0ovBK6e+2aW5W3SE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jn2gwJJENEaPu9naGwW3cXcwRWbYuNW12dPocDApGbRfUaFoWptD7IjUGmsTxH8qg +QzZBBWirz40IcpTPW254/zQgNc4Q4DUgxrib77Fc9ADSt5VgacCmKSHVByWofSOy2 IC3H5PosBTmjIFrWSTYA4W9l8fMur2L1JpuDrAqTGNsuBgeTF+WGtsP+iN/Q1UdvhQ agMIjwr/XUDp9P0EU3c+Nw9rP5l3HStLu03QW3jRFgkJpOQqaSG8rCw0+oRsHs8z5Y Sop7CyoSSUQ0co0IGtjsqqoPWEsnRKP2RnIkN33UO8E2PXf5uGjFUk/X4kE9GSzEEP DWoGv5WsZ6oDw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFmm-00000004in3-0b47; Tue, 05 May 2026 15:26:04 +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 v2 09/11] docs: maintainers_include: don't ignore invalid profile entries Date: Tue, 5 May 2026 15:25:56 +0200 Message-ID: <63228e005fcf3dc4583cee06905341e8bce84181.1777987027.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 Currently, there is a "P" entry for Rust pin-init that is neither a valid ReST file inside Documentation nor an URL. A proper fix is to either convert/move the file or point to a URL. Yet, the parser should be able to pick what's there and show on its output. Add a logic to display such files at maintainers-handbook. 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 572c382db2c2..74082bf5d4a4 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -240,6 +240,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 @@ -332,6 +334,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 Sat Jun 13 20:55:25 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 5695947DD72; Tue, 5 May 2026 13:26:06 +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=1777987566; cv=none; b=cMigu63Z65WitUz4uSgGNlysXQnOzz+InU9Vd2i1480o9uYVBnGh6CdygkfWruV3Bjm9+nhRv/vR7cRdkUxCfzvERuSjFAIsGCU64cpsuhwlrVi8yhyqQJLRsI5aGmbXvYBYYrWVj5P4bRo1ixBPZw4CtlMrogq2e6vMW5+e1RE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987566; c=relaxed/simple; bh=ji7IOhovAJkxdV5QZIeWOhYb6No0bgVbt8ZPTNNRvqc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=po+aZHPu9RKQnPG7a9Gb1ri8derZQzGV+oX0D/IgafzLFHk/WlRSSR02zeiSpZFLB8acdTAWNBmfqXPJ+TUDMvy8g0LYdZah4gC6bgvdw6IbZeFIv+KmKlKXIy58lMPUqn855ShQSawD9FhmCWln5xyWXeg5MdrKcC1uhjKW2D0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YTDScZkp; 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="YTDScZkp" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 0C387C2BCF4; Tue, 5 May 2026 13:26:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987566; bh=ji7IOhovAJkxdV5QZIeWOhYb6No0bgVbt8ZPTNNRvqc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YTDScZkpNHVSSJnpitQn8qa1lqbhO8iJfJJ0O039pkzEBkkSpo23VXRe9F6pW5sH4 iIkMY2zVOwRJu60Broo9VzZvFaPJu37NjduKEDjFF0fDWA5HQQ3RdW26UvfZWgQWuU bYsUnGqD3HIW9SYh9Z1fWZvonQ/0/nuUoKXnbPRzdl8qAUF7lhV4S93fsQybNN11O8 +Wy4QSEC5doB5BDQAJd8/A8MWFVQfK2GsDzS0Pcl5YmjZtUSdt7xachC2W7ycSHmTS o/UzUJm9dEwX6dVvYbh6eZzpV8Aq8OOjP86HkEvVi+Qpk33oKwbiq0tW0lxmN8r5rU C3YIqJsfTOAaA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFmm-00000004ioE-1IUI; Tue, 05 May 2026 15:26:04 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org Subject: [PATCH v2 10/11] MAINTAINERS: make clearer about what's expected for "P" field Date: Tue, 5 May 2026 15:25:57 +0200 Message-ID: <921e5e6a074f9d8cf77483d73e6801f49254bbb8.1777987027.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 "P" field is meant to point to a subsystem maintainer's profile, stored either at the Kernel documentation or on an extenal site. Make it clearer. Signed-off-by: Mauro Carvalho Chehab --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 2fb1c75afd16..8700472b3ae3 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -25,7 +25,7 @@ Descriptions of section entries and preferred order C: URI for *chat* protocol, server and channel where developers usually hang out, for example irc://server/channel. P: *Subsystem Profile* document for more details submitting - patches to the given subsystem. This is either an in-tree file, + patches to the given subsystem. This is either an in-tree .rst file, or a URI. See Documentation/maintainer/maintainer-entry-profile.rst for details. T: *SCM* tree type and location. --=20 2.54.0 From nobody Sat Jun 13 20:55:25 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 5897947DD75; Tue, 5 May 2026 13:26:06 +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=1777987566; cv=none; b=ar7kKd+YRCjEB+TO6tUKuKvKh0C4ampFyk3wkBUxYZFNOSxrXdBYw+oykL/DB/mjZpPpLB2v3fX4oIhw4GNTFk8vOkr8Z37AjTLbsRdwzHPJmS3LgVo4fR/1NhYs7xXJ41iH/IxHInFfGiSyxO6Cw8ba3w2YP6TMNzltHvNZyRQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777987566; c=relaxed/simple; bh=fkRw9ZQ/Nl/SEfPMSjG1656WDAr3XU2weNlQw7TtpvM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=AOrD4qZ4jfsE7LcTQALcq4uVgfZbRuEGZXKbBcCEorDHpDdCfK5CcAvdo8dBsTK3B8r/kYoJWo/EjudNM5+CPtAjh3yk4tqzp95jG1F58391ahqG30PH477X2v807M46ASY0k8OXMHukZc3VqZz7X1hVIQU8oNNHTdLOWsnIVAQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ToXNKaLK; 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="ToXNKaLK" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 36E15C2BCC7; Tue, 5 May 2026 13:26:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777987566; bh=fkRw9ZQ/Nl/SEfPMSjG1656WDAr3XU2weNlQw7TtpvM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ToXNKaLKcnlaqF/9haKDHnE3hf5TqX0XfMZQx7b3knq4Qxk/5PgPFJVRGp6IQoLrw 7x7gRFVxhCioX1brTd/qZi5yyHUx1MQBrnQWttR1p9pYc6doQ96XIwQ0vtS2TTEBrK 3gsxKe0DPyq2ict5X5nPCfNHlBZGXhVYTXB1lRJJ6jXF5yvR70N8hg0u5MUDAVw5og irZO7JJfCFK1XAJXo/eEVNP6pw2afnSR75utYxGmEkXzmjZzb9Rt7b5xvi16jsKg6k nhFvwE4gOOqAVV+n0yKY8tVqyVHmzJKqGmNpgs62P6kxVWYYUhRwtpfxMnhDYQ9sPv hGa+M4zrDjc1Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wKFmm-00000004ipP-20YD; Tue, 05 May 2026 15:26:04 +0200 From: Mauro Carvalho Chehab To: Benno Lossin , Jonathan Corbet , Linux Doc Mailing List 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 , Boqun Feng , Danilo Krummrich , Gary Guo , Miguel Ojeda , Trevor Gross Subject: [PATCH v2 11/11] MAINTAINERS: use a URL for pin-init maintainer's profile entry Date: Tue, 5 May 2026 15:25:58 +0200 Message-ID: <1bceee886b9027d66bbb48d9d6c8d1250ce8dbcb.1777987028.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 This maintainer's entry is not inside documentation nor is ReST, preventing Sphinx to create a hyperlink to it. Change it to point to the already-formatted URL. Signed-off-by: Mauro Carvalho Chehab --- MAINTAINERS | 2 +- rust/pin-init/CONTRIBUTING.md | 72 ----------------------------------- 2 files changed, 1 insertion(+), 73 deletions(-) delete mode 100644 rust/pin-init/CONTRIBUTING.md diff --git a/MAINTAINERS b/MAINTAINERS index 8700472b3ae3..b16c8f85d099 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -23402,7 +23402,7 @@ S: Maintained W: https://rust-for-linux.com/pin-init B: https://github.com/Rust-for-Linux/pin-init/issues C: zulip://rust-for-linux.zulipchat.com -P: rust/pin-init/CONTRIBUTING.md +P: https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md T: git https://github.com/Rust-for-Linux/linux.git pin-init-next F: rust/kernel/init.rs F: rust/pin-init/ diff --git a/rust/pin-init/CONTRIBUTING.md b/rust/pin-init/CONTRIBUTING.md deleted file mode 100644 index 16c899a7ae0b..000000000000 --- a/rust/pin-init/CONTRIBUTING.md +++ /dev/null @@ -1,72 +0,0 @@ -# Contributing to `pin-init` - -Thanks for showing interest in contributing to `pin-init`! This document o= utlines the guidelines for -contributing to `pin-init`. - -All contributions are double-licensed under Apache 2.0 and MIT. You can fi= nd the respective licenses -in the `LICENSE-APACHE` and `LICENSE-MIT` files. - -## Non-Code Contributions - -### Bug Reports - -For any type of bug report, please submit an issue using the bug report is= sue template. - -If the issue is a soundness issue, please privately report it as a securit= y vulnerability via the -GitHub web interface. - -### Feature Requests - -If you have any feature requests, please submit an issue using the feature= request issue template. - -### Questions and Getting Help - -You can ask questions in the Discussions page of the GitHub repository. If= you're encountering -problems or just have questions related to `pin-init` in the Linux kernel,= you can also ask your -questions in the [Rust-for-Linux Zulip](https://rust-for-linux.zulipchat.c= om/) or see -. - -## Contributing Code - -### Linux Kernel - -`pin-init` is used by the Linux kernel and all commits are synchronized to= it. For this reason, the -same requirements for commits apply to `pin-init`. See [the kernel's docum= entation] for details. The -rest of this document will also cover some of the rules listed there and a= dditional ones. - -[the kernel's documentation]: https://docs.kernel.org/process/submitting-p= atches.html - -Contributions to `pin-init` ideally go through the [GitHub repository], be= cause that repository runs -a CI with lots of tests not present in the kernel. However, patches are al= so accepted (though not -preferred). Do note that there are some files that are only present in the= GitHub repository such as -tests, licenses and cargo related files. Making changes to them can only h= appen via GitHub. - -[GitHub repository]: https://github.com/Rust-for-Linux/pin-init - -### Commit Style - -Everything must compile without errors or warnings and all tests must pass= after **every commit**. -This is important for bisection and also required by the kernel. - -Each commit should be a single, logically cohesive change. Of course it's = best to keep the changes -small and digestible, but logically linked changes should be made in the s= ame commit. For example, -when fixing typos, create a single commit that fixes all of them instead o= f one commit per typo. - -Commits must have a meaningful commit title. Commits with changes to files= in the `internal` -directory should have a title prefixed with `internal:`. The commit messag= e should explain the -change and its rationale. You also have to add your `Signed-off-by` tag, s= ee [Developer's -Certificate of Origin]. This has to be done for both mailing list submissi= ons as well as GitHub -submissions. - -[Developer's Certificate of Origin]: https://docs.kernel.org/process/submi= tting-patches.html#sign-your-work-the-developer-s-certificate-of-origin - -Any changes made to public APIs must be documented not only in the commit = message, but also in the -`CHANGELOG.md` file. This is especially important for breaking changes, as= those warrant a major -version bump. - -If you make changes to the top-level crate documentation, you also need to= update the `README.md` -via `cargo rdme`. - -Some of these rules can be ignored if the change is done solely to files t= hat are not present in the -kernel version of this library. Those files are documented in the `sync-ke= rnel.sh` script at the -very bottom in the `--exclude` flag given to the `git am` command. --=20 2.54.0