From nobody Sat Jun 13 06:00:19 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 D0907336EC0; Sat, 9 May 2026 06:56:52 +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=1778309812; cv=none; b=hD/0iAL4njxWOJxlUBDeKf9AT/OSYl2Sj86b4CIHtzksDJc1ojApck87A5w7o+J53qZZFkPUrUdZuuEvXJEbVAXrbLx2gUVayvIg7jBRBlZUrUN3CH73Mar9nQ1psQLYOysDTdf68LPFu9ObGb8fXYAGfxgZ0Sn/luOPYK23G3c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309812; c=relaxed/simple; bh=l2dzoBjQe6RzrONBJzpxV3PoxTBCSEMgrbS+QMaT4u8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ovvfvABRun0hwJXsJqmzOkIP9EwqZHX1LSr7gnSsR9AV65EmMyG+gvPRPXD0sxNzyhCjDD02xadn0F2N8RvorDKbqJlIQHrFg8tvk6nL/HwRS6dw2mflD3yjI3CjRvf6r3Cjs8QM5L6DGpnQeMPkQIWHjzry8JJp8/4MZGUpMF0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LZ1xLlar; 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="LZ1xLlar" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7E65DC2BCB2; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=l2dzoBjQe6RzrONBJzpxV3PoxTBCSEMgrbS+QMaT4u8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LZ1xLlarnhqwNLzMMaDDfEXfTfQUtHeBRofNH/L/3RQ73dJTNHH7XttDFcGHiVJg8 99V+fav3gc0F93wkk8WUbBS2hj2NhCjRrxfyipwid95vOCI9uAWWry8v/ziefzsqZE Z1BPh2ze3NWe4EyxGhwR7Vlg5Fg1o3lncOheUhJTqscV07sGWh+clnkGwrRmwDfUCk Hfs/y20/Dzhn9UzPecrbKDH+LDSsfLgvd7ptotrtXzmeef/T+KJ8geWq0OQusk+f61 ty3KyHLv7v+8z5rHeFRXSH2vppCDRYe8Z0dH6H/BLgtlFw4gqIlsdeEMtQYZJ71tJb I2swWeUFnit2Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GIb-29yo; Sat, 09 May 2026 08:56:50 +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 v3 01/13] docs: maintainers_include: keep hidden TOC sorted Date: Sat, 9 May 2026 08:56:34 +0200 Message-ID: <2742993764f2193101536a1cea40e034d75e0539.1778309595.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 Message-ID: --- 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 06:00:19 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 22F7F37DEBC; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=MQSkjgoTPrO3GE0C47h6mzYbD54rgOjqULcFytCktDZrrOyim2DYNWAPQ4Nd2GLcMC+D4wsDpViryqXnsxV0rW4Mk34L1CScOtGD6AtxInEJWnRaVud123c7xZNH6M07tYKE8rvXnwxyHLCzJgMNWbkbyOwx8KXIFXVLkXCqsbY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=xvcRgb9TiLjnGNqqDPmnVmMbvy8lkz8/SqQRrURabD0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=LFgkgbyqeOiIJW9XdA1jjKvHVWdoangHLs/1RllgaK7VPeGUdRca8ApF+2i1DMcfvG7ddG7ZheeNSQya9WJJu3knuYNq0vTVwwtXAM2RXDYlfhQjB9au+mxbVddQqAHcdX8beNG/0DZaqelXMrrVcdXijWm4rmo6yTnX5EJIutc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=WNYFA6x5; 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="WNYFA6x5" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 84C6CC4AF09; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=xvcRgb9TiLjnGNqqDPmnVmMbvy8lkz8/SqQRrURabD0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=WNYFA6x5CGwrbt4w2kUGHrcQVwirvEqubT6jYOboNE9WSG4htrIjc/JiBeWgFqez2 m+4b4PRJ8buRXQ5DIo90uiPEIhNxu0H4mDFqoIulwZeum4xsQ4qQCR5bd8Ut07dfcU dLqasB+xhUIaS7rLfS1xvFDmsO9sAiry6EeZa8lq0tlFZIpdn66e4QSTUvv6o7dyA3 6pITClb+Q8K5nUlU9W4vmWASnrAEpmcIOkQUhm2zvv42kCHpLMcfFiqOfGHYz0dkTn Gd125wZhjnFhUEkPecCS0L+c6l3OkrgvyOs7VMHmwXdRs4fRdgbUtoVDnRB+tIArfQ AAQkke39gmv1w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GIf-2H3Q; Sat, 09 May 2026 08:56:50 +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 v3 02/13] docs: maintainers_include: split state machine on multiple funcs Date: Sat, 9 May 2026 08:56:35 +0200 Message-ID: <26376e92a5e31e5d285b8676ed443a247b42e4c5.1778309595.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 Message-ID: <0b72530cf496ce5e2987ca784058a50f4dc814d2.1777987027.git.mcheha= b+huawei@kernel.org> --- 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 06:00:19 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 195C237C93E; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=EiMzRxG8Ko32DM/C5uSRV258N0wkdYbNBqpxMSKwei+sA4nTlUABUs9LrpnzIFtUwRi8a0rs8eL6anxsCgMH0LCIwoD+hHcMS/2YM+V9jwedSPvLVLCNtC9e4aC6m68vwhjTh/ZYIYfinw8EnjqCBBxTXJ2EDRRRxqLjR21L0z4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=58D6TREjKdd2Wm2oWjAknodr8BsKAXN/7isMMM/lcGI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CmMNzq2xWHngeHwCadPuARAkhlxVDaf1Z00xySnTZOwQrOA/UflvqWCbP3LG7Z6CuW8iWRMq9fJ6G6EH0xKvj8TJLmtMzVXR3mwYRpXWMzOP1BxOVao1ujuG6U3Fzm8ZtU1tPbLM4IGiwzEh7f3rZuA8mtySUici3oJWKFuaEPU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GLu5qk7G; 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="GLu5qk7G" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 98479C2BCFF; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=58D6TREjKdd2Wm2oWjAknodr8BsKAXN/7isMMM/lcGI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GLu5qk7GhIrT6JTMOnJQS/lbwBpaNqBA/bM6C3Amutwc27QLp99D5D5ntx6CTGHnN 36bCkZG21B706nInN17WJYKHFCoF91sKJzP68V5ZkCOyq5BbH0nOKcFnFtfUtBMAWU GmWXKWwgDGAxpZ1c8ekBhIxt6CzjroWtBYLQBn4j7BAUVaSn4HeT9h/kBi/NQeY/pB 85c2JzoezOuknVxasVOKkAXtq78v/bbWCvYYn1ZTIEtyOdab+c+qCJLJsWnUGjSvo4 uiBrcWGaWqc+xrrzCLDhM/6UX5ljtZvvNtf3FC1Ta5s9WatOq5AY82H5ZL6AuVeyJw Qqe4gvv2cpLaw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GIj-2O8m; Sat, 09 May 2026 08:56:50 +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 v3 03/13] docs: maintainers_include: cleanup the code Date: Sat, 9 May 2026 08:56:36 +0200 Message-ID: <5f48bf411925e923d206239a4de0a3e34592de88.1778309595.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 Message-ID: <24a83995778de8710cac40a3089c2f2fe5c38dbd.1777987027.git.mcheha= b+huawei@kernel.org> --- 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 06:00:19 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 D07E82D739B; Sat, 9 May 2026 06:56:52 +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=1778309812; cv=none; b=m8OFKcsY4/hIx65PLeI5XeViDO5l+xG/HxOse/x1kGTV1pSk7z+q878KGP3eVcZssVC7VtbY7y+QhKq+yf/Pewbk0hhOXKadjVbsddoYq19L9ONS5DCYqo3i3Hyn+A322a7mZA/QBtw5DYm7b08zi5CB+/Bwu/4fr4qyXoo5nsA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309812; c=relaxed/simple; bh=vvbVKXiMZTQ7JhI4IceyRauJ2Kf7XejKUUzqts3ZkGA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=slikEW87SLYQqsk604J5VgqiQ6K7CyMTx/fgmthXZLT42KbEn8r0D9i3i6K3cczTb3ohEItAvQ6+ibLrjwtV5yy99GE5QBqMqcDvlXkFqhm76X8UPy+FgMww4xgRUMRB+kwDVLbuKd20FHqu49+EORIvCd5liUtzJ7izgE6+yjQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=f27OjLSX; 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="f27OjLSX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 89AC7C2BCF6; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=vvbVKXiMZTQ7JhI4IceyRauJ2Kf7XejKUUzqts3ZkGA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=f27OjLSXF10mDRzIxJRJi2kMEbu7v5FrW83uIzrOrsTHwKumnDL1ZCgksuGRtJVrw tzg8xxRMe/HpcdA/wJ7feWniqrGcArSEpLuKCp4Ec5/SRQ/+anBLcYLQix+K93mJSD tI59ixx5AYPSId2RKFaVfhJhBlWM33nmBracqbwODidNB+jdqG/mrFTCUND2HoX6SD PTzELDDkAI64fltlzu2vNM+6sZabfOHteGkrotpsiupO0nth4LoS03GMMH5y7aGwSG isB5ZRaK1/JjKmGKcNTEnDLEkqz/U603EoK2ogmJqcomvX52B1Y3D0mvMZrT4I38FP ll+hQcESUa75Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GIn-2VLm; Sat, 09 May 2026 08:56:50 +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 v3 04/13] docs: maintainers_include: clean most SPHINXDIRS=process warnings Date: Sat, 9 May 2026 08:56:37 +0200 Message-ID: <567200712771590d08e4da096b4def92bf729ffe.1778309595.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 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 Message-ID: --- 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 06:00:19 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 168B037C935; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=JkTCclr4iMUemI1Z8mAUfIWh+Z/fELYWCN39Gh1AfAqHYJrkiQCo3l6T8gjswxns+yeFzlOMIfCbQwwgaXGbD2I0Z/UEtOmCRyrfKjCv9uYBW9h/UGeKA4ZG3CNQl3rSmzXSqIpfLP9Yr5hSNcg+uuiaaGdJrRJMNUThSHpR7Uw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=BYZw/6MTuax7OAtnTmgcyAUyW1L1i3w+/GoTm9mewYE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nqBryBCT/SY4o0xS8g3Ry2HdE4wKa8CDmTEDUyeX5DBKKW5u4TqIbW0A2mN2vNfVo9Un38WLWC6SEhbHHi+5O5Cdxo1BQFJFadgV6UuaFfNTquKbYPowKHMLlfh9YPHINF08eh/cj0k7O0wJGSltd0dax1MLyXeL1ntqPIx06b0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nR+ff6aA; 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="nR+ff6aA" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9388AC2BCFA; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=BYZw/6MTuax7OAtnTmgcyAUyW1L1i3w+/GoTm9mewYE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nR+ff6aA818HX04TznAYDM7C/eLQ7EhiiA+Muqdyf+o1SOlo5I+HWH3YIdTQCVLQD mRwZg93O1YSIBFFrhQzlRImF8G1DK+CrSxZW6cofx0mnLlMlCKLE04aTaqXP3PSMmO 9dvblG6XVc8QgSonhYj497T5IyO+C1QZdr7PZYpbAmo1D9h6Bsx6DMdqyEai5TkN83 tZf0++C6/7u61WQru4nC4NJxsKcOrWJgbyF6x5V/ZBNRwhd4TT5vb+rfphvDFGWL2z /MK0KfFp+i06cRWxj7opmXrIZOs6hNfkN23P7hs8Wpd0xJe5yKksrSwNTP5D26GVtu tksPry7dD1mOg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GIr-2cWe; Sat, 09 May 2026 08:56:50 +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 v3 05/13] docs: maintainers_include: do some coding style cleanups Date: Sat, 9 May 2026 08:56:38 +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 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 Message-ID: <460aabd0518f080b34e12fdc0beb7ec7685d5866.1777987027.git.mcheha= b+huawei@kernel.org> --- 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..345eb28804ff 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 extension""" + 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 06:00:19 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 D0780288530; Sat, 9 May 2026 06:56:52 +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=1778309812; cv=none; b=debaYKcrpajngqBWHndRD5cBwK2xvFVR/Gyxwzu6eXMUHHvVGtoUGJ3a85SluVMhCZmBAC+J/EELHXAt4gInCqvVqfGU7tmCk4VE54AUPtToUvx81Zl75yzljZ2Uk2HXBdQ2Skvi8QVnyQiuXJA9DRRMHl07RG9rcc/X8VEj/gU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309812; c=relaxed/simple; bh=xKx76+aLteSfJDFOU+fNmwoI11MnqmCUXFoZhfsqPIQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=cIhWr/rLq3OfZGF2cSFHzOAnCVvGmEHqFRCYx4hzIiZvguMQXHskCBz/MRcH4MYiYranAW5XI+JDwYXumhlQDxVc8gI8h6eo1defS2J1MjVFnd8venk6a3kTGVoXHCb0p73jeElUtOCWX5lY32EBypVatTLzUSIPjMiVluYopSE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=t2Q1mdZB; 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="t2Q1mdZB" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 80886C2BCC9; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=xKx76+aLteSfJDFOU+fNmwoI11MnqmCUXFoZhfsqPIQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=t2Q1mdZB38fDnMx/U+tjw0cFqbJ/YXYSG2nOpBMHXCWFCODXdZRw2k0vT6Ge+bIgC D+xb5vQou6In2hvGV9QfyCy6Cu4fcsuzOhapboQYsrI4XeG/k+zHpIFiNhdI2rAnrH U2fwt7Awp6idP7deKPk4U+yv5d2ldu01aE2e6OK9BYTgNfiUbUuZsCQfrGUcviqhFy 6xBjmPx2Se5RA4LrsgWTLrZCWEoyxxE2pnLQj9iIg2U/YJMfjsdXgjAwZExXPlFY/0 xjredj208ZZCmVGMVXyRnTJjdFpStZNjjTy1UrXokiGHLHdTkCcZE52BwFvauwCbIN x3OWU0imr2GyQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GIv-2jgS; Sat, 09 May 2026 08:56:50 +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 v3 06/13] docs: maintainers_include: store maintainers entries on a dict Date: Sat, 9 May 2026 08:56:39 +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 Message-ID: <4ad88179e03436984f29780ae380d50591f86c67.1777987027.git.mcheha= b+huawei@kernel.org> --- 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 345eb28804ff..ed9cd7b3dc66 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 06:00:19 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 0F12237BE9A; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=lFHnSONYyv3JYT7Hq1P9HN+1i82ZFowFYOHcJuZ4CsJtPzPlmuX3hOEPNrW7493gh4HQDKWaOari6xcvcJ29xkFm93Tu3w16d//LAhF72LrfW6HhmIdsVs23+AlV2hYg95VVZQQSwkkBxpjb2w0/R2hSb1HLziuOuLT11kH78JI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=mOVVsCv5LtyhTiEhZWzDwCJGXjoTo0YDPqDCnaKHxhQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nMen0skVLap25AqX1Fc/LsuS9TsQ7qH3UVCSbOXCRP1Bq4HL2eg00w7Q4T6MrrblaIs51zNi6BvTcUxeuPf4m5HXK5auGEhiZAQMD5Oboi1m+3FYeqZEPgJsUkT+i1AI2Uy1lLZ6rEreFdtTdo4R2QFqPDURKVwjYbuIp1TQ4gY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=diFwpkYd; 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="diFwpkYd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8E97CC2BCF7; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=mOVVsCv5LtyhTiEhZWzDwCJGXjoTo0YDPqDCnaKHxhQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=diFwpkYdkmfGTqeg1I5ddLz5SCgCpDvr/J7YozBM8HVsr1FCpx1yg0mwNbiLDMsut io8A/NLc2UBPpcIzRgjXO3k2Z1RucV9fa6dVHsVdMakdg6fbf4Prx1s0xXoOJIk9Mq lDVLrQ0Zp+UFxurUEbYXXGUvoceyD6fIn65cWMn3oKgVV47rsYRW19wPMi5gDsl/Gl aUDUOuldGsyWmFosH6+fi9hBaRUy0ver1ynh2aHaO1wzGKok0Ds4z28pshfIBqr3ZK nxNdFc8kJB1U7wadnp7h2xOBC7kXa7J4OIMzl01eiNsl9y+kCOK+9qAEJVmYyf14WG xqUhL1yaBRLmQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GIz-2qs0; Sat, 09 May 2026 08:56:50 +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 v3 07/13] docs: maintainers_include: properly handle file patterns Date: Sat, 9 May 2026 08:56:40 +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 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 Message-ID: <89127706fb3493d00ecb21e528c8a27081e5ed40.1777987027.git.mcheha= b+huawei@kernel.org> --- 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 ed9cd7b3dc66..5361774b61bc 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 06:00:19 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 0EF4C37BE84; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=ih2zPY1w96OPIaxM/UClM4ZjF6GfYSmy98CPd/KSqmKZIl+zkWWspUcNd+q0pcEIMDYPmW/klWf03s3P+JB7NwrvMlJ7LWQxf7J00gZPFNgjt2iH1y9XJj0cOAjFHDtCRD3vb768uDc99FuawaXfjl/K2IXTmNNy9XgBlTSrlOM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=bEdOgLYVqkkGnoZZ0qDzIRXAOJCAVtybGm//EcR6R4A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=le7X8wCxNff4jn9RRuD1CEcyQboaxFceDPoQwFUJr5grEWJiZKGK5fJK3/c3ygv3IQmxVe3IInoCbffXFqgJqtrysyGhIDFERw1biHHTfKmBF1U0fuwFBk3zhk9CY9va4cmnUqVOXdxtsxX1/GGPf5v21kZDjXiu0US80MTkDaY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=MUIba6a7; 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="MUIba6a7" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 911E7C2BCFB; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=bEdOgLYVqkkGnoZZ0qDzIRXAOJCAVtybGm//EcR6R4A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MUIba6a7EZsAXQeN1EuhVFKfaGGq4DeEVrq9ZzvGlPmPXYEZR6JbiS9DhDO4zFsvj YE6MXRTcqbp2EdnWOi8EsVnfFLBoEboIatcRV29iQnZ5RNQ83aJ5qjt1j6mdpw0W+E UFGDvny5rBfaPLkerJXpBa9VW0EyYGbMuEVmt3gRL2IeS5HsZc4tVZhofxnEEPwmcR AyTRhwqhsYh+7OVxio6hrCiRP+6Y3IM0/MTfZS4hAy/M+6J/MNdUogzvJj5xpmlNUQ DoRCzmA3SkxQBzrxfpTHh4SZml/PHhBIzmyocfKMDaYPIi5XfRNT3Ti5FUw4no9zTT UrkBHTyIq/A6w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GJ3-2y0X; Sat, 09 May 2026 08:56:50 +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 v3 08/13] docs: maintainers_include: add a filtering javascript Date: Sat, 9 May 2026 08:56:41 +0200 Message-ID: <6f87c233351595358fddba11d42171be464f0a65.1778309595.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 Message-ID: --- 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 5361774b61bc..7035754a1c66 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 extension""" 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 06:00:19 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 0EEBE37BE71; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=V9KTGgqx2vTeTidi3Yl9qVD4bhGPwQTAlt9HeaQDb7mBHqUoCH/nOtCVmI+d4BDc+7bWs0GUJ7y5nstyzQ2y14iKmKqThOeOwNlOltYo9MBb0mOlBhMEw1Q/dmRCDlWSWEQPNDkH57QeFkPk5RkXwXoj5LGhvh42wbP2mh9TtXk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=gsoRMnvNN6edah3oPgUMaTpEDfU7uOambafbgeXQ/3s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=QWDYhqkkS8TxsVeVLgln610dF5u+HIw4V4xNRu+OJBETP/m0qCCajcLi8fimQQiQn4Z/gFlTK9YGtV+eOeomq2AUIPOcn4p2bioL46wm9N4skXng+ocz3GTleS8vsBtuJVdkiEMhzl8m3RMqzdVIuEBtxkulDO46UUgZHzGAR8s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Ex2mb0L6; 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="Ex2mb0L6" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 960AFC2BCFC; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=gsoRMnvNN6edah3oPgUMaTpEDfU7uOambafbgeXQ/3s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ex2mb0L6BYdXTrSN+WYsAO9UuCrQ7U0294tYEDYty1x5Bu3wsn7V/dywF6GPpY5Ck EbDm16sxnFRnonq6K29zWN2Md692UAq/aqjzpspfMzEaSt+mIRXajwVWEujKwFgSqc R8r/cnSujfSr3BwEvJfKcmwiUJmEoLgpPDWM5Hu3AHGbThVUHQH51JR884WIf604el XMLUwO68wuNHWOXCuThuL2l51UI2iqG7La16jUbVeXkUqB7wudmV4DqZxjSmYvTflS eA1k3QkrJ6q1j6PtG+HpmyQ20ph0jOlDE2AnloY17I4apynOyG+uXN8ailOekiqn/y E9fk/rg5Ptiaw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GJ7-35K2; Sat, 09 May 2026 08:56:50 +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 v3 09/13] docs: maintainers_include: don't ignore invalid profile entries Date: Sat, 9 May 2026 08:56:42 +0200 Message-ID: <98915f35442fa12c6d59611083aea3adbf8c6aff.1778309595.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 produce a warning when this happens. Message-ID: <63228e005fcf3dc4583cee06905341e8bce84181.1777987027.git.mcheha= b+huawei@kernel.org> Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 7035754a1c66..073a10575872 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 @@ -328,12 +330,15 @@ class MaintainersProfile(Include): # output =3D "" for profile, entry in sorted(maint_parser.profile_entries.items()): - profile =3D profile.title() + name =3D profile.title() =20 if entry.startswith("http"): - output +=3D f"- `{profile} <{entry}>`_\n" + output +=3D f"- `{name} <{entry}>`_\n" + elif entry.startswith("`"): + output +=3D f"- {name}: {entry}\n" + self.warning(f"{profile}: Invalid 'P' tag: {entry}\n") else: - output +=3D f"- :doc:`{profile} <{entry}>`\n" + output +=3D f"- :doc:`{name} <{entry}>`\n" =20 # # Create a hidden TOC table with all profiles. That allows adding --=20 2.54.0 From nobody Sat Jun 13 06:00:19 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 D097F33CE80; Sat, 9 May 2026 06:56:52 +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=1778309812; cv=none; b=Zp1aIzDwUVLNjeHF9KZK83m8yekZYcJd7+Zr+6biiGDC7MtprxC2OL6g8XJbSXF0AqqKk9/RxEv1CEZCE1RNpkqehjsthHpbXWhzWE2bS7S2QD6WIFXlvTdRsPkZnYZMvzmQcivSwQIYhceSFPBD5uqNSCmAle+RKehMCOc78to= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309812; c=relaxed/simple; bh=k9b6iREAcYovXmkSWuj6Zi9Oc/0Ei0eob0uGnTRB3iE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=C9XgBk5fJ2VhYgtoPTGlTWQ5SV9Q8yacZBQOhjLEKx++N5C89SMJoUgXDqsBnWIxbS+ke8QauW/9UtZoqyI0LiUztgGeDMbkvRV0vrFaXJD3QpQbmMUkcUFEvxOr11VZgixvQGElqOfeToqrlaOgOSmyzCZj80TRhH1lJ/NU+cU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ErsCJVri; 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="ErsCJVri" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8BF79C2BCF5; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=k9b6iREAcYovXmkSWuj6Zi9Oc/0Ei0eob0uGnTRB3iE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ErsCJVri3PtVIaNXdUDGywcbtu7EM/UBB5VLuG8WL7dNgvhXTII/GG1EjRSZpCjzZ RY8v5U9xTPY6FiLgmKqaGX67Hbv3Za4QJbUnQl1MF2w/4MOicv9pgi0KDxymyGl/hI L6BBbbB56bO0eTEtLge0BWYXsKOycbBb5jMKTjdeRUYxhjdOhmV5klG7N++8ase25t tTYOzkgVsQyWZGO1WlHagxDqftxTO68xTeBFhFIzQiRRPb/eeOGmz/EiJAO9TR1g9E L5TD0fIUM3Zp+rhq8dyPZ+HieDT4MBiTb7VV66wrmjizMMKR6o0QW+NZSD0oKDJ45D /C23xvwoMqKJw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GJB-3CCt; Sat, 09 May 2026 08:56:50 +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 v3 10/13] docs: maintainers_include: better handle directories Date: Sat, 9 May 2026 08:56:43 +0200 Message-ID: <2b07e12eaa07bf81824ad427335783b170e01dba.1778309595.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 TOC tree needs to use paths relative to the document containing the maintainers-profile-toc directive. Fix it. While here, address a warning from sashiko-bot, which points that using partition can be problematic if the root Linux path ends being something like: foo/Documentation/linux/ causing the documentation dir to be at: foo/Documentation/linux/Documentation Very unlikely, but fixing it is trivial: just use regex to pick the last one. Notice that I dropped the comment about using os.fspath() as the logic already uses os.path.abspath() which should work equally well. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 28 ++++++++++++--------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 073a10575872..8c7b79721edd 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -82,7 +82,7 @@ def ErrorString(exc): # pylint: disable=3DC0103, C0116 class MaintainersParser: """Parse MAINTAINERS file(s) content""" =20 - def __init__(self, app_dir, path): + def __init__(self, base_dir, app_dir, path): self.path =3D path =20 # Poor man's state machine. @@ -92,8 +92,8 @@ class MaintainersParser: =20 self.subsystem_name =3D None =20 - self.app_dir =3D os.path.abspath(app_dir) - self.base_dir, _, self.sphinx_dir =3D self.app_dir.partition("Docu= mentation") + self.base_dir =3D base_dir + self.app_dir =3D app_dir =20 self.re_doc =3D re.compile(r'(Documentation/([^\s\?\*]*)\.rst)') =20 @@ -323,6 +323,8 @@ class MaintainersProfile(Include): =20 def emit(self): """Parse all the MAINTAINERS lines looking for profile entries""" + env =3D self.state.document.settings.env + docdir =3D os.path.dirname(os.path.join(env.srcdir, env.docname)) path =3D maint_parser.path =20 # @@ -347,7 +349,9 @@ class MaintainersProfile(Include): output +=3D "\n.. toctree::\n" output +=3D " :hidden:\n\n" =20 - for fname in sorted(maint_parser.profile_toc): + for f in sorted(maint_parser.profile_toc): + fname =3D os.path.join(maint_parser.base_dir, "Documentation",= f) + fname =3D os.path.relpath(fname, docdir) output +=3D f" {fname}\n" =20 output +=3D "\n" @@ -381,15 +385,15 @@ def setup(app): """Setup Sphinx extension""" global maint_parser # pylint: disable=3DW0603 =20 - # - # NOTE: we're using os.fspath() here because of a Sphinx warning: - # RemovedInSphinx90Warning: Sphinx 9 will drop support for represent= ing paths as strings. Use "pathlib.Path" or "os.fspath" instead. - # - app_dir =3D os.fspath(app.srcdir) - srctree =3D os.path.abspath(os.environ["srctree"]) - path =3D os.path.join(srctree, "MAINTAINERS") + app_dir =3D os.path.abspath(app.srcdir) + match =3D re.match(r"(.*/)Documentation", app_dir) + if not match: + raise ValueError('Documentation directory not found.') =20 - maint_parser =3D MaintainersParser(app_dir, path) + base_dir =3D match.group(1) + path =3D os.path.join(base_dir, "MAINTAINERS") + + maint_parser =3D MaintainersParser(base_dir, app_dir, path) =20 app.add_directive("maintainers-include", MaintainersInclude) app.add_directive("maintainers-profile-toc", MaintainersProfile) --=20 2.54.0 From nobody Sat Jun 13 06:00:19 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 D089B325727; Sat, 9 May 2026 06:56:52 +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=1778309812; cv=none; b=sitilF6t6lbNfGP+Utj1Vr6tCHvgRAicRJQXKf9Zxev8atRWY3TRKwLlk6LVZOcCJNpVOjY5o0d4ruPdXbyfz3uirD/v2JPM0WcAzd4NOxJT88dyUoG9rSaEdSvRk67eNmyd6sfOGP4Gh+oAJtWI+SO0KqrhpjhQPHKodJBsDHo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309812; c=relaxed/simple; bh=Ahut7zTu/U3hZrEkjrlS4vv3JRMDz0WHhByOcY8s0Ws=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=G6x4WvQFzSmQ/+XRab0O0BAsfDV2psi0h7FjyzpjjlY9BD7K3BHXNEDwxzJXDnvmAzNqw6250dtZvaP3qrE6a7NQFMKuQ8hiG8xMhKDnGpm7GUJXVPsrKiL2bL2y1Oez8zo9raaZ25dNkz3JNC2ma45MCkr5tTnDIj3CxIED4G8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rYkUbYhi; 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="rYkUbYhi" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8297FC2BCF4; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=Ahut7zTu/U3hZrEkjrlS4vv3JRMDz0WHhByOcY8s0Ws=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rYkUbYhitlbvvWaW1509ftEODdMGes0h+yqtNPsTYY5TuHlJOHtg/f+Aby3OXn1kF RuM5Bjx5asQ1obucE8rvBNspckVsSH+uZkv/eIsE532Kmyn6/NnwMWdBT8iu/D+/96 O4U8CjNuxqBBXo0utgIPXmmxtfvsWIbdIrpu8a8jgnk4+Ym+OIGelqS7Kuz7pnmM+J mwM8D1IdvMdhVPYpT1tm04ACWMo455KqxOAfkAErNP4KOugyzOfQDHDleH6G5YgvkD OuXosmCWVZWEqV0cTifKK+8xFXhDBYKt/WwRJYFkuc77HYrF+taxWu9esUUmceUmsi 8j9LMhRAwyhvw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GJF-3JBd; Sat, 09 May 2026 08:56:50 +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 v3 11/13] docs: maintainers_include: better handle doc wildcards Date: Sat, 9 May 2026 08:56:44 +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 As warned by sashiko-bot, the new logic doesn't handle wildcards on Documentation/. Change the logic to properly handle it, cleaning up the code to remove some code duplication. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/maintainers_include.py | 103 ++++++++++---------- 1 file changed, 53 insertions(+), 50 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 8c7b79721edd..be8e566e0363 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -95,7 +95,7 @@ class MaintainersParser: self.base_dir =3D base_dir self.app_dir =3D app_dir =20 - self.re_doc =3D re.compile(r'(Documentation/([^\s\?\*]*)\.rst)') + self.re_doc =3D re.compile(r'(Documentation/(\S*)\.rst)') =20 # # Output variables with maintainers content to be stored @@ -132,29 +132,47 @@ class MaintainersParser: # Retain previous line for state machine transitions. prev =3D line =20 + def get_entries(self, text): + """Generate refs to ReST files in Documentation/""" + + if "Documentation/" not in text: + return None + + if "*" in text or "?" in text: + m =3D self.re_doc.search(text) + if not m: + return None + + doc_list =3D glob(m.group(1), root_dir=3Dself.base_dir) + else: + doc_list =3D [text] + + entries =3D {} + for doc in doc_list: + m =3D self.re_doc.search(doc) + if m: + 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") + + if entry.startswith("../"): + html =3D KERNELDOC_URL + ename + ".html" + entries[entry] =3D f'`{ename} <{html}>`_' + else: + entries[entry] =3D f':doc:`{ename} `' + + return entries + def linkify(self, text): - """Linkify all non-wildcard refs to ReST files in Documentation/""" + """Return a list of doc files converted to cross-references""" =20 - m =3D self.re_doc.search(text) - if m: - fname =3D m.group(1) - ename =3D m.group(2) + entries =3D self.get_entries(text) + if not entries: + return text =20 - 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) - - return text + return self.re_doc.sub(", ".join(entries.values()), text) =20 def parse_descriptions(self, line): """Handle contents of the descriptions section.""" @@ -206,35 +224,15 @@ class MaintainersParser: # Handle profile entries - either as files or as https refs # if field =3D=3D "P": - match =3D self.re_doc.match(details) - if match: - fname =3D match.group(1) - ename =3D match.group(2) + entries =3D self.get_entries(details) + if entries: + for e, link in entries.items(): + if "html" not in link: + self.profile_toc.add(e) =20 - 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 - # + self.profile_entries[self.subsystem_name] =3D link =20 - if entry.startswith("../"): - entry =3D KERNELDOC_URL + ename + ".html" - else: - entry =3D "/" + entry - - if "*" in entry: - for e in glob(entry): - if "html" not in e: - self.profile_toc.add(e) - - self.profile_entries[self.subsystem_name] =3D e - else: - if "html" not in entry: - self.profile_toc.add(entry) - - self.profile_entries[self.subsystem_name] =3D entry + details =3D ", ".join(entries.values()) else: match =3D re.match(r"(https?://.*)", details) if match: @@ -243,7 +241,9 @@ class MaintainersParser: else: self.profile_entries[self.subsystem_name] =3D f"``{det= ails}``" =20 - details =3D self.linkify(details) + details =3D self.linkify(details) + else: + details =3D self.linkify(details) =20 # # Mark paths (and regexes) as literal text for improved @@ -340,7 +340,7 @@ class MaintainersProfile(Include): output +=3D f"- {name}: {entry}\n" self.warning(f"{profile}: Invalid 'P' tag: {entry}\n") else: - output +=3D f"- :doc:`{name} <{entry}>`\n" + output +=3D f"- {entry}\n" =20 # # Create a hidden TOC table with all profiles. That allows adding @@ -356,6 +356,9 @@ class MaintainersProfile(Include): =20 output +=3D "\n" =20 + # For debugging the pre-rendered results... + #print(output, file=3Dopen("/tmp/profiles.rst", "w")) + self.state.document.settings.record_dependencies.add(path) self.state_machine.insert_input(statemachine.string2lines(output),= path) =20 --=20 2.54.0 From nobody Sat Jun 13 06:00:19 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 0F03D37BE88; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=RORgpeuPHCSQB/U1DY8kBp15LwJU8sq6n97MGuWRECJNcu3N8TfT9x5vP/ZMDlnDNpLuOUfBuO0bAO/Njcmq3ZrccP0aHJ2d2/PpRja34x8wgRAsJ6FftjT35vZ7qpTiQKr+TrqkTPoXgD8mLxAbJAWlj1h4KembX50F6bPs6K0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=rUXLJYcWROxoaAwRXs6Dg6TASbey7uzPX2TcdL/dM34=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=PLeeAdjAnQ2SbdxRNKwN/qJ+jVRo/jd56dbsWobyyx/PPRGKOGwBvDQytjfgQh3J5yY+B76o/O0GWDuaxl9h4HmVL/GZaLVIdKiWccanHG+P7GeGT8K7tVdIzvDrPaCnyl8bu/h+qHR3sEKT9cV/B0IiYkfZwl6MAqxaQvHlJhk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=n0pX1H4T; 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="n0pX1H4T" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9AB3CC2BCFD; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=rUXLJYcWROxoaAwRXs6Dg6TASbey7uzPX2TcdL/dM34=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=n0pX1H4TVfDa289w0zjA2AypTm2JKzhI8fdcUnPGxW7t2O9KE/B0iNIG8fjUmEaH6 xliUmWYhPqEX4RI2YSqv85eDsEqpStr8cTWTvSZzXE1xZQb7lD7kw3tTKPtlA6VTvD b2plQSSbvelpwSNkI+09fZe9uyohH1jUBavZtIY+4tgt2feE8XXEzkk8W7Md7qISte N7pDVLogovJqHRV+/QfDuHFGSDg676fr4CPov1tOlmGf5Czzjwk5haRfIrBYokgWHZ VhHut+nvfnPFhriKVZx7MIzJB5FMEKV2AR+ymMb9rCUnC6gqecFGe7sJIioY6COOLj M0ezjVOn2cfYw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GJJ-3Px4; Sat, 09 May 2026 08:56:50 +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, Mauro Carvalho Chehab Subject: [PATCH v3 12/13] MAINTAINERS: make clearer about what's expected for "P" field Date: Sat, 9 May 2026 08:56:45 +0200 Message-ID: <21e6def8b69bac36795dcd4047d663bb31407dcb.1778309595.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 external site. Make it clearer. Signed-off-by: Mauro Carvalho Chehab Message-ID: <921e5e6a074f9d8cf77483d73e6801f49254bbb8.1777987027.git.mcheha= b+huawei@kernel.org> --- MAINTAINERS | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/MAINTAINERS b/MAINTAINERS index 2fb1c75afd16..77244b7f9545 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -25,9 +25,9 @@ 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, - or a URI. See Documentation/maintainer/maintainer-entry-profile.rst - for details. + patches to the given subsystem. This is either an in-tree .rst file + inside Documentation/, or a URI. + See Documentation/maintainer/maintainer-entry-profile.rst for detai= ls. T: *SCM* tree type and location. Type is one of: git, hg, quilt, stgit, topgit F: *Files* and directories wildcard patterns. --=20 2.54.0 From nobody Sat Jun 13 06:00:19 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 1613E37C927; Sat, 9 May 2026 06:56:53 +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=1778309813; cv=none; b=VwdIF3kOyrqp0uEoz+PEjfw7KcTqdGSSoYR2wzpzA9i6wOhcwcimhLPs+lgsbUCF9AaKRfdTweuX01Eeu/dxwp+cR1ZjC77eZnC+wCMVtpncW16tX7fdedjcCCPct5N8DfW2CqH/znfS4l9VDHUu0GeqCaLZkwk0bwREYBUzK6s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778309813; c=relaxed/simple; bh=EBEG6jjE7Xv7G7J6Z3BZCIJYD1aVH2l9srB6VgRlOys=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=EAyOVypJz96TImFfFPZ8bn/doTaD47iUk8JCoYHzbXU0DvadwdV9Vnhlw5bNRgpjOzm9P0obPpLQ+XX6JcGsAd6JBG7ZPeWi+uqVliid3s2i8lpHP088R1+vKTgvCd0YS31oI5CdtEbvwmEZmn754QMiboHYT2nEiXjwA9LWovM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=BysW1rLI; 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="BysW1rLI" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9B185C2BD01; Sat, 9 May 2026 06:56:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1778309812; bh=EBEG6jjE7Xv7G7J6Z3BZCIJYD1aVH2l9srB6VgRlOys=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BysW1rLIzw7p1aiCgyiDLd2XEMVglxsp/j8mBvWMJAsH1AkU2+rewIu+fFD8udOJU F7acP88Rvfm060W+wg+LWUc/sCJWrLfwhqeK/MTPDouq1UcYNz215tQ3UnmP+QPTJY D1bfqwWQ7RVJxERDmlBL4Tp6iu5wy2FXWLhByZExgMX0MiG5oVu1Xlz9fUi8uV6EHq IBI1iVGiRNrEsp3xMzY+36SPHT/PN1ZPUFoGSjXjg1gidKHPSG6LL3w0OVmcxn2bVJ jlRJcokUrZLJtTwh2TVsT4sadRd8XkToIbKm9LBd4g/mVAZLj4Q2PWD6QkXWF4Ln36 NPOVdUPDKqLRg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wLbcI-00000000GJN-3XGM; Sat, 09 May 2026 08:56:50 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Miguel Ojeda 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 , Mauro Carvalho Chehab , Trevor Gross Subject: [PATCH v3 13/13] MAINTAINERS: use a URL for pin-init maintainer's profile entry Date: Sat, 9 May 2026 08:56:46 +0200 Message-ID: <59144e7323b95166e61a7c7f84096a0b9bb5d26e.1778309595.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 Message-ID: <1bceee886b9027d66bbb48d9d6c8d1250ce8dbcb.1777987028.git.mcheha= b+huawei@kernel.org> Signed-off-by: Mauro Carvalho Chehab Acked-by: Gary Guo --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 77244b7f9545..dd424a4f9f3b 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/ --=20 2.54.0