From nobody Mon Jun 15 23:14:10 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 C73773D3CEE; Mon, 27 Apr 2026 14:22:35 +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=1777299755; cv=none; b=qIdUn+eyJ/wEEUHr+RSUllXcB/n3jwDeVAfBNnhjxKccyAFdSPN1CyeGv26+f4OWMBv+CcIUPDkyUNtn0GhBGGjcArvj56NBUrR/Qr4C5BUCC3bFVw/SOFkHEpkG+t/IjgVr4meb1maZ/uXZKc08j6OWZYePxH1c2P7ObxEWJNA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299755; c=relaxed/simple; bh=oCSFDjePyMaj2tf0ATqd8TtAxNzPuU0qXsi2GNKPtg0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=GQcMDcONBqj5IhD8tP7AmLey8A2vc+GkvRHDxEX07scZi6yK5Sp6PP8kWgSlzJcddZmy82FJD98iSgtpHkhThLplgDMjX7ZsJFLihmko8D8sEzF1iML0UjuGgaghjGtN4JaR9RkcOb3tqYrm5/MDSCmPAE9FZ3pSLgYuXg066Rw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=g63i3v69; 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="g63i3v69" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7540AC19425; Mon, 27 Apr 2026 14:22:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299755; bh=oCSFDjePyMaj2tf0ATqd8TtAxNzPuU0qXsi2GNKPtg0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=g63i3v69KbfKbKetN4/ng4W39CIC+KAcr2DVio5NMr0E4SOYq9KFSx6bxPcZXi/dm eu3upyCETiw70SWV0kJsDEGoc1xqBhfbEnbCbhbKHYFKEQX2oHwU+U5x1qul9KM1+I 9Km8AIqYJHLu7LLFoaFgv1aqzUhraX8hzDVOxGWmiAq/tPxGkBRdM8jX6qqTmKBRAj eX0LcvhKbRkyUCkDyPkIl7VjT4rgxvDBbJ4ktlNsaM5/LLeEmSaMxhuOjmIKY1gVHK Cz3UqTfIuTrn7Tz4VC6/YN3zuhVn1lNAc58kVAdgPO5eM9DIhzJxWSOWWSbQqzIq3G 04gotTEtDGwWg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr3-0000000C8Q5-2cjW; Mon, 27 Apr 2026 16:22:33 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan Subject: [PATCH v4 01/10] docs: maintainers: add SPDX license to the file Date: Mon, 27 Apr 2026 16:22:19 +0200 Message-ID: X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab While this file is really trivial, add a SPDX license line on it. Signed-off-by: Mauro Carvalho Chehab Reported-by: Randy Dunlap Suggested-by: Dan Williams --- Documentation/process/maintainers.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/process/maintainers.rst b/Documentation/process/= maintainers.rst index 6174cfb4138f..5d1b1464c3ae 100644 --- a/Documentation/process/maintainers.rst +++ b/Documentation/process/maintainers.rst @@ -1 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. maintainers-include:: --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 DC1FE3D34BA; Mon, 27 Apr 2026 14:22:35 +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=1777299755; cv=none; b=JralyUHY6Ni+cCSnzT/mHCNgvRjRMZ9AMZOTL71Gn+Dcs0LgJVz9iAdIUU5K61Sjr4OBZienwW/aono9THS0JW4mqHBWdJrIP7O5BMZAvd+n9Ei9yUqF9MvG4YYBuXlXiAOa+Mk34FuqNVAvwjg0cDzOyPvKtQW1jNxbXMjgH1o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299755; c=relaxed/simple; bh=yDbfJtWAfvQ/qhk2RPsW8RGaJCDeeTNMtQ/iIuIjsIA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=gRF9sIaOv1JW0863wpd3lIkv0wsKnASy6L0cCBxhNH8ZpjcTNh5gwPdJIY8nnF8VhH2ovCSo1zncNlVskl7Nbyw4cz2UfGPwBbCjxtIUSp9p0iR6oi3/wnZhT6BIhzNGgsG6v7iGHg1HYL3GE5O7bZ5A2rmf0AVMnz6lxIyTK28= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Mz1ODkev; 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="Mz1ODkev" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9F96BC2BCB7; Mon, 27 Apr 2026 14:22:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299755; bh=yDbfJtWAfvQ/qhk2RPsW8RGaJCDeeTNMtQ/iIuIjsIA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Mz1ODkevkS59ZL/Qj3MnHx1QPKpMvCimI0lPx3/AITa2C88Ll99AX9eIVgptSFKxt 0SXMGaMcxCTIA/RBDDrkYLK2lmD2Sc5Z3TzH+/07trUaV+GFns6NbJd1qQlpLLzRl6 sIEm+PmJFYZn11iJnhqIU+c+tjUcuJWLmaBrpJSNI+250R1k+a80xfzRzfi+m0Zljn Grj7v9UzerlRN402+lmg2Gtsn3+ULQ0I3QS3qTL00lmRRM3RIUyUchF+bMzfczZzSh GjZEJl046o3yqiPhb8GMtrSQ2XpnxkDhDDVB7ouzRNUB/wSesuc9w+BKVy9baVZGsC 83YAcZCVaSXIA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr3-0000000C8RI-3LGz; Mon, 27 Apr 2026 16:22:33 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan , Dan Williams , Randy Dunlap Subject: [PATCH v4 02/10] docs: maintainers_include: auto-generate maintainer profile TOC Date: Mon, 27 Apr 2026 16:22:20 +0200 Message-ID: X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Add a feature to allow auto-generating media entry profiles from the corresponding field inside MAINTAINERS file(s). Suggested-by: Dan Williams Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-de= v.notmuch/ Acked-by: Dan Williams Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mcheha= b+huawei@kernel.org> Reported-by: Randy Dunlap --- Documentation/sphinx/maintainers_include.py | 93 +++++++++++++++++---- 1 file changed, 76 insertions(+), 17 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 519ad18685b2..1dac83bf1a65 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -21,6 +21,8 @@ import sys import re import os.path =20 +from textwrap import indent + from docutils import statemachine from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include @@ -30,20 +32,11 @@ def ErrorString(exc): # Shamelessly stolen from docuti= ls =20 __version__ =3D '1.0' =20 -def setup(app): - app.add_directive("maintainers-include", MaintainersInclude) - return dict( - version =3D __version__, - parallel_read_safe =3D True, - parallel_write_safe =3D True - ) +class MaintainersParser: + """Parse MAINTAINERS file(s) content""" =20 -class MaintainersInclude(Include): - """MaintainersInclude (``maintainers-include``) directive""" - required_arguments =3D 0 - - def parse_maintainers(self, path): - """Parse all the MAINTAINERS lines into ReST for human-readability= """ + def __init__(self, base_path, path): + self.profiles =3D list() =20 result =3D list() result.append(".. _maintainers:") @@ -78,6 +71,12 @@ class MaintainersInclude(Include): # Drop needless input whitespace. line =3D line.rstrip() =20 + match =3D re.match(r"P:\s*(Documentation/\S+)\.rst", line) + if match: + fname =3D os.path.relpath(match.group(1), base_path) + if fname not in self.profiles: + self.profiles.append(fname) + # Linkify all non-wildcard refs to ReST files in Documentation= /. pat =3D r'(Documentation/([^\s\?\*]*)\.rst)' m =3D re.search(pat, line) @@ -165,12 +164,23 @@ class MaintainersInclude(Include): for separated in field_content.split('\n'): result.append(separated) =20 - output =3D "\n".join(result) + self.output =3D "\n".join(result) + + # Create a TOC class + +class MaintainersInclude(Include): + """MaintainersInclude (``maintainers-include``) directive""" + required_arguments =3D 0 + + def emit(self, base_path, path): + """Parse all the MAINTAINERS lines into ReST for human-readability= """ + + output =3D MaintainersParser(base_path, path).output + # For debugging the pre-rendered results... #print(output, file=3Dopen("/tmp/MAINTAINERS.rst", "w")) =20 - self.state_machine.insert_input( - statemachine.string2lines(output), path) + self.state_machine.insert_input(statemachine.string2lines(output),= path) =20 def run(self): """Include the MAINTAINERS file as part of this reST file.""" @@ -186,12 +196,61 @@ class MaintainersInclude(Include): =20 # Append "MAINTAINERS" path =3D os.path.join(path, "MAINTAINERS") + base_path =3D os.path.dirname(self.state.document.document.current= _source) =20 try: self.state.document.settings.record_dependencies.add(path) - lines =3D self.parse_maintainers(path) + lines =3D self.emit(base_path, path) except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) =20 return [] + +class MaintainersProfile(Include): + required_arguments =3D 0 + + def emit(self, base_path, path): + """Parse all the MAINTAINERS lines looking for profile entries""" + + profiles =3D MaintainersParser(base_path, path).profiles + + output =3D ".. toctree::\n" + output +=3D " :maxdepth: 2\n\n" + output +=3D indent("\n".join(profiles), " ") + + self.state_machine.insert_input(statemachine.string2lines(output),= path) + + def run(self): + """Include the MAINTAINERS file as part of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + # Walk up source path directories to find Documentation/../ + path =3D self.state_machine.document.attributes['source'] + path =3D os.path.realpath(path) + tail =3D path + while tail !=3D "Documentation" and tail !=3D "": + (path, tail) =3D os.path.split(path) + + # Append "MAINTAINERS" + path =3D os.path.join(path, "MAINTAINERS") + base_path =3D os.path.dirname(self.state.document.document.current= _source) + + try: + self.state.document.settings.record_dependencies.add(path) + lines =3D self.emit(base_path, path) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + return [] + +def setup(app): + 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 + ) --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 DC2953D3D13; Mon, 27 Apr 2026 14:22:35 +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=1777299755; cv=none; b=Tya+fDhWjMstg7CL/c7gt1noNviHgpnUVpmIqEjHAdZwY5+AcrPzWjnUALN4h/bSKZdVS/ALpyxQbFColitljQ8UvfF4ddQr308iFlAdSDIDdLMNfIvRMP1UGZ95SjwfHzmSc8frtFhcCRsgyUe/M+qSCa1X6ZnZqWZ0xSo/hto= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299755; c=relaxed/simple; bh=j3FNDw94v8Js77BMKKlIjikDyVc4ICEKPAd65qeaksk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=MbFbsytPqbhXTP2shu3XZxapw0t95xcdCbL/ChQ8zmQgMP586wssqEyqSaSUqDw68bjmeS+ugVmw++xdXakEhwCWwU6OqUEsjXUCrRsb+oS+POUav0jB3d8i5zL648/2W1x3AIf1TeAJbdXnvth9zvEiw632H3+9iuYLDzN4p4A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FjCszoNX; 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="FjCszoNX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A5BD0C2BCC6; Mon, 27 Apr 2026 14:22:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299755; bh=j3FNDw94v8Js77BMKKlIjikDyVc4ICEKPAd65qeaksk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FjCszoNX41yosXCm8y2WyfUJPjvPcYVYlvUqrcsuFwC6xY5onb/lokMz6gIKDUOkJ N+HfMM6+2jAncU67tcNf0KxPDrMaz8x/sLs78ANbVKUOnQWcYsaip9vzqZXE2Jj3Pv buyUx6jz+hLcdr5RuyCJsb0N48RW22T5eQwK/x6337UgPFs7AmIkwaLeAZ2L3rxtl+ KhJUvE2USnOJouFP7NB6u6zX+kNKUAN+ZDKQqwblRpIPk8YFCRr3pvKXLerJ+nxkWj TJCQAxSXGBS7iE8IFcfpckteGV8v+H6TOc2iuvHxGa2VBmgUjwxCJgsTS/essJUu8v tQPHhVd7hqO3w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr3-0000000C8SV-43Hr; Mon, 27 Apr 2026 16:22:33 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Albert Ou , Alexandre Ghiti , Palmer Dabbelt , Paul Walmsley , Shuah Khan , Dan Williams , Randy Dunlap Subject: [PATCH v4 03/10] docs: auto-generate maintainer entry profile links Date: Mon, 27 Apr 2026 16:22:21 +0200 Message-ID: <65e3f1d51eda0984ac945f50128b593f848584bc.1777295258.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Instead of manually creating a TOC tree for them, use the new tag to auto-generate its TOC. Co-developed-by: Dan Williams Signed-off-by: Dan Williams Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Message-ID: <9228f77b0339b8e5dea4a201ab6d4feb30cef5c2.1776176108.git.mcheha= b+huawei@kernel.org> Reported-by: Randy Dunlap Suggested-by: Dan Williams --- .../maintainer/maintainer-entry-profile.rst | 24 ++++--------------- .../process/maintainer-handbooks.rst | 19 ++++++++------- 2 files changed, 14 insertions(+), 29 deletions(-) diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Docume= ntation/maintainer/maintainer-entry-profile.rst index 6020d188e13d..58e2af333692 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -92,24 +92,8 @@ full series, or privately send a reminder email. This se= ction might also list how review works for this code area and methods to get feedback that are not directly from the maintainer. =20 -Existing profiles ------------------ +Maintainer Handbooks +-------------------- =20 -For now, existing maintainer profiles are listed here; we will likely want -to do something different in the near future. - -.. toctree:: - :maxdepth: 1 - - ../doc-guide/maintainer-profile - ../nvdimm/maintainer-entry-profile - ../arch/riscv/patch-acceptance - ../process/maintainer-soc - ../process/maintainer-soc-clean-dts - ../driver-api/media/maintainer-entry-profile - ../process/maintainer-netdev - ../driver-api/vfio-pci-device-specific-driver-acceptance - ../nvme/feature-and-quirk-policy - ../filesystems/nfs/nfsd-maintainer-entry-profile - ../filesystems/xfs/xfs-maintainer-entry-profile - ../mm/damon/maintainer-profile +For examples of other subsystem handbooks see +Documentation/process/maintainer-handbooks.rst. diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation= /process/maintainer-handbooks.rst index 3d72ad25fc6a..531985a0fae8 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -7,14 +7,15 @@ The purpose of this document is to provide subsystem spec= ific information which is supplementary to the general development process handbook :ref:`Documentation/process `. =20 +For developers, see below for all the known subsystem specific guides. +If the subsystem you are contributing to does not have a guide listed +here, it is fair to seek clarification of questions raised in +Documentation/maintainer/maintainer-entry-profile.rst. + +For maintainers, consider documenting additional requirements and +expectations if submissions routinely overlook specific submission +criteria. See Documentation/maintainer/maintainer-entry-profile.rst. + Contents: =20 -.. toctree:: - :numbered: - :maxdepth: 2 - - maintainer-netdev - maintainer-soc - maintainer-soc-clean-dts - maintainer-tip - maintainer-kvm-x86 +.. maintainers-profile-toc:: --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 25DBD3D412D; Mon, 27 Apr 2026 14:22:36 +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=1777299756; cv=none; b=lWq8poC8N1GQeov5Qy3bVaRiANfHL/WzgqyCFCKpa8FWkPJUiXR/j8ug8h2xWGhnh/03cU2C81eaGxDa/3FMFv491T9FKXMaBHMEMBjWvBIMDwxKhn0ppaxtXQjs2InEdK8UzDvL3r9kGst2ZZZhXybyb8AHTAOJUlNdu4rucbE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299756; c=relaxed/simple; bh=E3XaUZpwsbd6HDm3kWl1GEnwhRzHLxZQZYqA7/UzEm8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ZPEaF7MsEsg30uwdeo9D/5MUouP/o7uf42FvKFiIp8Myk0zriEW8lcNx4tZvwOsYHcoxvJYTTtn0gefH1+/mqDes8ipWUDT5uUC2+9EuVWr5+uHwN/99F8COCYCUEnAjaU0Fj5kYnWerQnHHGa/Mze0iSe6vwxZLKN9K/uMSt1I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=BOteI6RP; 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="BOteI6RP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CFB0AC2BCB9; Mon, 27 Apr 2026 14:22:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299755; bh=E3XaUZpwsbd6HDm3kWl1GEnwhRzHLxZQZYqA7/UzEm8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BOteI6RP2hQ5Z8VatsZNOi56HYMeReNNnUeCHpMNypzzBRNowIuk5Q8afZX9a9PuO inRDkHUDgcbnLqyqZtlcSfqh385oY7p8gL7HPeMKCAGXbLLsWW8Zrv/w9JTrUsMiFk UtN4rbfUJtOKV3ntu63AfKhdrOURcxVTzkKyihzDFDLs1Jj36eJc3mwhwGM+zBYTfj NFn4knlPTflKCWqQigA8KnTSurceJAf7JKMFLBeRkyavSHY3yjObIRgLyDa8dtHGFI 3/jp1tdUMpjiR+Dnq7mU1oflgRB8F1V1PCRsId/w5nF3dxYcCP2NWBXmUOOdrk+pTv EY8vQwRsQ/bQQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr4-0000000C8Ti-0aGO; Mon, 27 Apr 2026 16:22:34 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan , Randy Dunlap Subject: [PATCH v4 04/10] docs: maintainers_include: use a better title for profiles Date: Mon, 27 Apr 2026 16:22:22 +0200 Message-ID: <8ce9c77c4d8c98e6bad37d838b0e359c8416040c.1777295258.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab As we're picking the name of the subsystem from MAINTAINERS, also use its subsystem name for the titles. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reported-by: Randy Dunlap Suggested-by: Dan Williams --- Documentation/sphinx/maintainers_include.py | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 1dac83bf1a65..cf428db7599c 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -36,7 +36,7 @@ class MaintainersParser: """Parse MAINTAINERS file(s) content""" =20 def __init__(self, base_path, path): - self.profiles =3D list() + self.profiles =3D {} =20 result =3D list() result.append(".. _maintainers:") @@ -54,6 +54,7 @@ class MaintainersParser: prev =3D None field_prev =3D "" field_content =3D "" + subsystem_name =3D None =20 for line in open(path): # Have we reached the end of the preformatted Descriptions tex= t? @@ -75,7 +76,10 @@ class MaintainersParser: if match: fname =3D os.path.relpath(match.group(1), base_path) if fname not in self.profiles: - self.profiles.append(fname) + if self.profiles.get(fname) is None: + self.profiles[fname] =3D subsystem_name + else: + self.profiles[fname] +=3D f", {subsystem_name}" =20 # Linkify all non-wildcard refs to ReST files in Documentation= /. pat =3D r'(Documentation/([^\s\?\*]*)\.rst)' @@ -112,6 +116,8 @@ class MaintainersParser: output =3D field_content + "\n\n" field_content =3D "" =20 + 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)) @@ -217,7 +223,13 @@ class MaintainersProfile(Include): =20 output =3D ".. toctree::\n" output +=3D " :maxdepth: 2\n\n" - output +=3D indent("\n".join(profiles), " ") + + items =3D sorted(profiles.items(), key=3Dlambda kv: (kv[1] or "", = kv[0])) + for fname, profile in items: + if profile: + output +=3D f" {profile} <{fname}>\n" + else: + output +=3D f" {fname}\n" =20 self.state_machine.insert_input(statemachine.string2lines(output),= path) =20 --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 66ACB3D47AA; Mon, 27 Apr 2026 14:22:36 +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=1777299756; cv=none; b=YhzVKgCKCjBixtIMEXIBVSD8iWr8SbszNP+fw4xsFgAE7TbQ9FCbL3iHDxf1Uvdax1/bGRjrxMyFlEN3nZU/LwXoKOl2r2XqjQ5w+AKdhDpEkjgJM+GsE9iWAELo43Rw9fVujXu9vuqP8KBXXkNLLiILXVOss8zGG1dy+/n1AuM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299756; c=relaxed/simple; bh=0shH3sYNJw46ZXhUBb7ZZLmWnfDxlkyIXiYSyyLbk7s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=tVd4dwIAW/k6YlPrZT2EB6C9apmNIDzaZ2ZLbesLJNRo4GOI6jrwf/jhrx5MkAZs4N9ve1Doak+QjoSCYCbxqedAyUSUYVE5zUftAch8pWmb9yNxEWr8ZKAOJ5yCO1UbssYiISUAJfnBRpgzDShyJQgO48R9SzEghBblc2fOQF0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KSup6Xk2; 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="KSup6Xk2" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2C2F7C2BCC4; Mon, 27 Apr 2026 14:22:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299756; bh=0shH3sYNJw46ZXhUBb7ZZLmWnfDxlkyIXiYSyyLbk7s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KSup6Xk26SVjls6PE/k9vVIVVI6u3N5Rk9SnIReyU1IeMSq1yASSm5JH8JzMfSlqO Bnb/HSoN7iSgsLAIK3eQZSzuIvlsKEE/dHQAd/nU5ie5u11L7PnT6RIWs6oShHWK4M q1s9Gyqyb4Yo9ID+9vf9tulnDQw1UzZHIMOzhwP4SNDUvdWF2hExZq/gDwdOF3igCv Qijz1icL5PinDyMeY/0Sz2eaA8I0Z1EaB7dwUgMvG9RE4Y9zJ4RKxfL19S9VPNuooG qX7SzXfh8uFw929UVLuiTvG5r0pDwxro5TKSt60bsHY7/oibd+WD6nq3h1gl+WLKzS 5GC075n3amDSg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr4-0000000C8Uv-1Ixw; Mon, 27 Apr 2026 16:22:34 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan , Randy Dunlap Subject: [PATCH v4 05/10] docs: maintainers_include: add external profile URLs Date: Mon, 27 Apr 2026 16:22:23 +0200 Message-ID: X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Some subsystem profiles are maintained elsewhere. Add them to the output. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reported-by: Randy Dunlap Suggested-by: Dan Williams --- Documentation/sphinx/maintainers_include.py | 28 +++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index cf428db7599c..f1b8d4b00c2a 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -37,6 +37,7 @@ class MaintainersParser: =20 def __init__(self, base_path, path): self.profiles =3D {} + self.profile_urls =3D {} =20 result =3D list() result.append(".. _maintainers:") @@ -81,6 +82,16 @@ class MaintainersParser: else: self.profiles[fname] +=3D f", {subsystem_name}" =20 + match =3D re.match(r"P:\s*(https?://.*)", line) + if match: + url =3D match.group(1).strip() + if url not in self.profile_urls: + if self.profile_urls.get(url) is None: + self.profile_urls[url] =3D subsystem_name + else: + self.profile_urls[url] +=3D f", {subsystem_name}" + + # Linkify all non-wildcard refs to ReST files in Documentation= /. pat =3D r'(Documentation/([^\s\?\*]*)\.rst)' m =3D re.search(pat, line) @@ -219,18 +230,31 @@ class MaintainersProfile(Include): def emit(self, base_path, path): """Parse all the MAINTAINERS lines looking for profile entries""" =20 - profiles =3D MaintainersParser(base_path, path).profiles + maint =3D MaintainersParser(base_path, path) =20 output =3D ".. toctree::\n" output +=3D " :maxdepth: 2\n\n" =20 - items =3D sorted(profiles.items(), key=3Dlambda kv: (kv[1] or "", = kv[0])) + items =3D sorted(maint.profiles.items(), + key=3Dlambda kv: (kv[1] or "", kv[0])) for fname, profile in items: if profile: output +=3D f" {profile} <{fname}>\n" else: output +=3D f" {fname}\n" =20 + output +=3D "\n**External profiles**\n\n" + + items =3D sorted(maint.profile_urls.items(), + key=3Dlambda kv: (kv[1] or "", kv[0])) + for url, profile in items: + if profile: + output +=3D f"- {profile} <{url}>\n" + else: + output +=3D f"- {url}\n" + + output +=3D "\n" + self.state_machine.insert_input(statemachine.string2lines(output),= path) =20 def run(self): --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 837C63D47B5; Mon, 27 Apr 2026 14:22:36 +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=1777299756; cv=none; b=BGuMtZe7ThU2bBnBF8+xSnizgddlK9Z7OuGa6Pl76EaxxrBIMxdlXy93dFSQa65GeILoFGoiWmYB+2iHPZ96al9+0ANHpf1E9Y0o14gvnCRYpsfA50BlZ9uBFMf/56E5mCxFa0Eb4Hi6Ele8eqf9dkKJoomB5R2dWxe/37qjB1w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299756; c=relaxed/simple; bh=vIA3xtTJnuuolAuvS6pYp2PgkibgyICdVHSyrMYfBXw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nvfvA+0mkg9BGAsnqVRUlKsFXWF6b0oAFvelT/JMg/BhAkVGsL96wCMaWkQKAyVuBA3wLvKG4R+SRr3NHzoENFmUQNrgGGdHX1ntZ1PAqYv9TmakcLSx1ujtiB7ZeanJNECrYKu2Hh1budnIZRRN5BuB0JuIBHD36Z4zAOW2TfQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=qyplwXDG; 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="qyplwXDG" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5C3BDC2BCB5; Mon, 27 Apr 2026 14:22:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299756; bh=vIA3xtTJnuuolAuvS6pYp2PgkibgyICdVHSyrMYfBXw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qyplwXDG3ZO3dPSj7lrcyH0Uc/XnzeaOG28ON5TnK+07AvmDZfS2Af3Oqt6jLS/On sCMNUlpLg2U5Tc3wqda952zNLk2Nf/qjln7doh53LOyWRNuq/qCZk9a5EMfjBu+lJB /mE7iXLP1BuZE5P4raDIYmxC1+GoieEvp0lxGrwbIe+e6+4x18b5aGzbZphrP3neEd E/fYnKXVo4tHqERZAlG3eoOuopUL2EPk5vbuG69+rviBNBC9HbilPdg+q7zr7QXTYB m+VOy/U/0QIzu4o3TXQdpBh9jUSocnf21cmF187cyUm8n5IKwdUF4vWPc/dFgCP8GI w/i42V0eZtsJg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr4-0000000C8WB-239G; Mon, 27 Apr 2026 16:22:34 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan , Randy Dunlap Subject: [PATCH v4 06/10] docs: maintainers_include: preserve names for files under process/ Date: Mon, 27 Apr 2026 16:22:24 +0200 Message-ID: <46961bc932be804cec19f06d202c23423d4aa12a.1777295258.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab When a maintainer's profile is stored outside process, they're already included on some other book and the name of the filesystem may not be there. That's why the logic picks the name from the subsystem's name. However, files directly placed together with maintainers-handbooks.rst (e.g. under Documentation/process/) is a different history: those aren't placed anywhere, so we can keep using their own names, letting Sphinx do his thing. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reported-by: Randy Dunlap Suggested-by: Dan Williams --- Documentation/sphinx/maintainers_include.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index f1b8d4b00c2a..948746b998a3 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -76,11 +76,13 @@ class MaintainersParser: match =3D re.match(r"P:\s*(Documentation/\S+)\.rst", line) if match: fname =3D os.path.relpath(match.group(1), base_path) - if fname not in self.profiles: + if fname.startswith("../"): if self.profiles.get(fname) is None: self.profiles[fname] =3D subsystem_name else: self.profiles[fname] +=3D f", {subsystem_name}" + else: + self.profiles[fname] =3D None =20 match =3D re.match(r"P:\s*(https?://.*)", line) if match: --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 A1FCB3D47C5; Mon, 27 Apr 2026 14:22:36 +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=1777299756; cv=none; b=hVy67PkWNXOGpstwtfIsxhDcvB53rMpJ+Y2y8/F/HvyndFwsg1ys5WE2IgPV/8yhY8Okk7uc5qY0k7VPJYXlbiboyVFQq+gMgH/qiAflcvPCy/BVkulGk4hggOXLxTgA6fIHm9x0uJw3Q8szOGxBTLO8yurZ1gzHY89S/IuwVUY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299756; c=relaxed/simple; bh=TwW+kGBiliF/Ei1obwlR1vu04Y0GBFL6iuNTaetPprg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CcQKrWMcB5khK3ZBHYwGhLDqA4aUy1Iaq7ARhbdBGrWoroYoKXZsXri6zdfKqtRO7xrkEP76p9s3hQZ4wzDhristYl5ai8dKQb2mG95q7D3tdUjKBtYligcNQyVUc2rEcw90M8O6F8pP80jTH1bv8vwlDiSGoVhnGCCo7zQ3rjI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=mSTMxd4T; 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="mSTMxd4T" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 82A19C2BCFA; Mon, 27 Apr 2026 14:22:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299756; bh=TwW+kGBiliF/Ei1obwlR1vu04Y0GBFL6iuNTaetPprg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mSTMxd4ToDGCw3AxRUTma98KSYjRKZe53RGL9TAtSIEZtuWS2RmKM8qWcPvWm/24C ULgkySwstM1BDHcLs1onK2XyEdh0eNVKSLbQIhzOxKNGwyJsHjKidR8MN4vomVLsLa xuSft7SpOwXeVyGvpxYinrZ9TKPMmG38Jc0FJ6xviwPo9vi74dgrZ+3lGW780trybI OxRnioRbLzTkr5CM2xAlSrnoB+w3rQe6mgO5j/36BKx0NQNBWY0If7aFI9U6KxvNkM 11xsXjZ6oLHy22AofaeV4izPXnoort71M92uIa7bhaO8+eFCqEWyHeX26oN2tteAms 0OO6WlKFGKTQQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr4-0000000C8XO-2lV7; Mon, 27 Apr 2026 16:22:34 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan , Randy Dunlap Subject: [PATCH v4 07/10] docs: maintainers_include: Only show main entry for profiles Date: Mon, 27 Apr 2026 16:22:25 +0200 Message-ID: <387b42c523e7b9f33e61cdff6fadb1df265cf71d.1777295258.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Instead of showing as a "Contents:" with 2 identation levels, drop its title and show profiles as a list of entries. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reported-by: Randy Dunlap Suggested-by: Dan Williams --- Documentation/process/maintainer-handbooks.rst | 2 -- Documentation/sphinx/maintainers_include.py | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation= /process/maintainer-handbooks.rst index 531985a0fae8..3821e78aefc0 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -16,6 +16,4 @@ For maintainers, consider documenting additional requirem= ents and expectations if submissions routinely overlook specific submission criteria. See Documentation/maintainer/maintainer-entry-profile.rst. =20 -Contents: - .. maintainers-profile-toc:: diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 948746b998a3..7ab921820612 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -235,7 +235,7 @@ class MaintainersProfile(Include): maint =3D MaintainersParser(base_path, path) =20 output =3D ".. toctree::\n" - output +=3D " :maxdepth: 2\n\n" + output +=3D " :maxdepth: 1\n\n" =20 items =3D sorted(maint.profiles.items(), key=3Dlambda kv: (kv[1] or "", kv[0])) --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 BE7C53D47DD; Mon, 27 Apr 2026 14:22:36 +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=1777299756; cv=none; b=Tmyk1Em5J7DptZ7RzL5mvn67afJ7asGT0AaYjwfUDZH8W1UaCTPEx/b/bjKpUTznRXzFVFd8u271tdfnIRhg9WB+TCcG1yCTsGLtKmAVrDMTsT0Ms0T2Xq4RWPwrKFhWb72IHdhSNXk2FnGJ/xHPFY8V4U9CDqIC3cAt8REhOF8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299756; c=relaxed/simple; bh=I5vPs/IWujzOHVh7PrTDW0lngtg+Gz1odrK4JwsYFaI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dGg2NRUHgM/ESi522WKIkD6hKxM16aTmCtpQf2QVdTC+Lg91ozoCCRjSGFiYn0nnubHHvHxAfYMEdqpLtwDRgaswyZwzCyT4FYRWv2+X9TjdaSMvCzSChXN2LTlAVLVRi9uHopD6SHUFQmcohs2nEKH8RUK05wGhUvfssUn4+3Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Zdi4fMzY; 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="Zdi4fMzY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9D2C3C2BCB9; Mon, 27 Apr 2026 14:22:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299756; bh=I5vPs/IWujzOHVh7PrTDW0lngtg+Gz1odrK4JwsYFaI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Zdi4fMzYladiP2JQ9zuFLVErYm0Kl2UnOLXTgxZKuPk4xSkP0LcI3Ih064AWuLEkF 9uxKTzH+hknWIb2bPxZWx8q1ad4KvNpKQROAy4cdhoz4+8UQTtZgQKvxfuYbXmnNYC 4I4iS5nPSbCNoB4w3oGe7ngDOPTA75PoPAsCwJl0rQBEI0iCD6BhOpiRvOqNmKzovW zc6hr/exBtFhJK1VAk839f5KE0EmZkCM8q/+NzIrc760m5PWivahr7h38tEVXzJfKn 8rtHfkpLpnP7nA4jo9QnFJnmS+L6udzUopaF6FKtmemgr69d6TuuZi7KGPvBQTIkQA o6U6FifntJ3Xw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr4-0000000C8Yb-3U8y; Mon, 27 Apr 2026 16:22:34 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan , Randy Dunlap Subject: [PATCH v4 08/10] docs: maintainers_include: improve its output Date: Mon, 27 Apr 2026 16:22:26 +0200 Message-ID: <10d06a3f530e07ad981aba93617a9a7f4d63c408.1777295258.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab There are three "types" of profiles: 1. Profiles already included inside subsystem-specific documentation. This is the most common case; 2. Profiles that are hosted externally; 3. Profiles that are at the same location as maintainer-handbooks.rst. For (3), we need to create a TOC, as they don't exist elsewhere. Change the logic to create TOC just for (3), prepending the content of maintainer-handbooks with a sorted entry of all types, before the TOC. With such change, we can have an unique sorted list of profiles, having the subsystem names used there listed. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reported-by: Randy Dunlap Suggested-by: Dan Williams --- Documentation/sphinx/maintainers_include.py | 76 +++++++++++---------- 1 file changed, 40 insertions(+), 36 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 7ab921820612..5413c1350bba 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -21,7 +21,7 @@ import sys import re import os.path =20 -from textwrap import indent +from glob import glob =20 from docutils import statemachine from docutils.parsers.rst import Directive @@ -36,8 +36,8 @@ class MaintainersParser: """Parse MAINTAINERS file(s) content""" =20 def __init__(self, base_path, path): - self.profiles =3D {} - self.profile_urls =3D {} + self.profile_toc =3D set() + self.profile_entries =3D {} =20 result =3D list() result.append(".. _maintainers:") @@ -73,26 +73,24 @@ class MaintainersParser: # Drop needless input whitespace. line =3D line.rstrip() =20 + # + # Handle profile entries - either as files or as https refs + # match =3D re.match(r"P:\s*(Documentation/\S+)\.rst", line) if match: - fname =3D os.path.relpath(match.group(1), base_path) - if fname.startswith("../"): - if self.profiles.get(fname) is None: - self.profiles[fname] =3D subsystem_name - else: - self.profiles[fname] +=3D f", {subsystem_name}" + entry =3D os.path.relpath(match.group(1), base_path) + if "*" in entry: + for e in glob(entry): + self.profile_toc.add(e) + self.profile_entries[subsystem_name] =3D e else: - self.profiles[fname] =3D None - - match =3D re.match(r"P:\s*(https?://.*)", line) - if match: - url =3D match.group(1).strip() - if url not in self.profile_urls: - if self.profile_urls.get(url) is None: - self.profile_urls[url] =3D subsystem_name - else: - self.profile_urls[url] +=3D f", {subsystem_name}" - + 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 =20 # Linkify all non-wildcard refs to ReST files in Documentation= /. pat =3D r'(Documentation/([^\s\?\*]*)\.rst)' @@ -234,26 +232,32 @@ class MaintainersProfile(Include): =20 maint =3D MaintainersParser(base_path, path) =20 - output =3D ".. toctree::\n" - output +=3D " :maxdepth: 1\n\n" + # + # Produce a list with all maintainer profiles, sorted by subsystem= name + # + output =3D "" =20 - items =3D sorted(maint.profiles.items(), - key=3Dlambda kv: (kv[1] or "", kv[0])) - for fname, profile in items: - if profile: - output +=3D f" {profile} <{fname}>\n" + for profile, entry in maint.profile_entries.items(): + if entry.startswith("http"): + if profile: + output +=3D f"- `{profile} <{entry}>`_\n" + else: + output +=3D f"- `<{entry}>_`\n" else: - output +=3D f" {fname}\n" + if profile: + output +=3D f"- :doc:`{profile} <{entry}>`\n" + else: + output +=3D f"- :doc:`<{entry}>`\n" =20 - output +=3D "\n**External profiles**\n\n" + # + # Create a hidden TOC table with all profiles. That allows adding + # profiles without needing to add them on any index.rst file. + # + output +=3D "\n.. toctree::\n" + output +=3D " :hidden:\n\n" =20 - items =3D sorted(maint.profile_urls.items(), - key=3Dlambda kv: (kv[1] or "", kv[0])) - for url, profile in items: - if profile: - output +=3D f"- {profile} <{url}>\n" - else: - output +=3D f"- {url}\n" + for fname in maint.profile_toc: + output +=3D f" {fname}\n" =20 output +=3D "\n" =20 --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 0E65E3D525B; Mon, 27 Apr 2026 14:22:37 +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=1777299757; cv=none; b=Rc7NPK/VzBYH5QQ5xMIUI0D2UfcgXBi0FBQtnvYNxhTjVzZo6P7cCNKzkJkreSyTodPfWpr6mErrUE/7RyosPTWqwhzTiTjC2DiQ303z5jgYEBmwBqB9QgKOVsC3n2NAnfVCQAUtjczXRDICH1cp98UIc6lvbwdxQaxp9pichew= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299757; c=relaxed/simple; bh=bli3EmeSILPYzmn9eMR6QOYwGG7x2r3ZAQx0Kn863sw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=POZSrZWHOkNIfOqpRgjKgNt2te0EOVV+zZUsFz2htiEpeSM5YvVcOSG79OEkZa/uGDQD0WvUqv9tY3gSkWnhKFgDdU26fxt2l++hU2G+toFbp9Acdsu4m5syPw516mdW+GHvwvPnMtBBElyzNqEJml1BfZ3YJNZrCjWhHDNJwWg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uY5dv9eN; 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="uY5dv9eN" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AE85CC2BCB7; Mon, 27 Apr 2026 14:22:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299756; bh=bli3EmeSILPYzmn9eMR6QOYwGG7x2r3ZAQx0Kn863sw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uY5dv9eNpHSI3Yhtmx6RBg7/lUB9sKj4GhdjwAyO+qkSn1w1KJ1k50F0b5KTFn1Zx ALcMbSdg7zz+lTH5Esyq10c8OTv1iQhqKnvKbhs0u1dTA54mr+Gd+Ofs4Bc/5pqSB6 JGpf2JlrTQ32vYlnDp6iPIkgnroILrviS2VQr7X/WwZIs+wd1YDknZb7X43Pz152BH BGSsJz8P7EF4XnJKNSbCjTzT/xHVMV2MaHqQKwq2aK8lHPeERmsA+GPBSuEUW0EboY rxUyOwF+xwRiiqGkzA5N1zKa5FrJH9DbFzg5NeMRGTm497ule6UsMdsJLVEwy/Ub/F RxWhk5g8QTiqQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr5-0000000C8Zo-0106; Mon, 27 Apr 2026 16:22:35 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan , Randy Dunlap Subject: [PATCH v4 09/10] docs: maintainers_include: fix support for O=dir Date: Mon, 27 Apr 2026 16:22:27 +0200 Message-ID: <193792d73d08d9f8b9faa8b3df8a1a7439344a28.1777295258.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab os.path.relpath() will do the wrong thing with O=3Ddir, as the build system uses "cd " internally. Solve it by using app.srcdir, which, on normal cases, point to Documentation/, or, when SPHINXDIRS=3Dprocess, it will be set with Documentation/process. While here, remove a dead code while writing maintainer profiles, as now all entries should have both profile and entry. Reported-by: Randy Dunlap Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7= a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970 Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Suggested-by: Dan Williams --- Documentation/sphinx/maintainers_include.py | 71 +++++++++++++++------ 1 file changed, 50 insertions(+), 21 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index 5413c1350bba..ae52e8198750 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -27,15 +27,24 @@ from docutils import statemachine from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include =20 +# +# Base URL for intersphinx-like links to maintainer profiles +# +KERNELDOC_URL =3D "https://docs.kernel.org/" + def ErrorString(exc): # Shamelessly stolen from docutils return f'{exc.__class__.__name}: {exc}' =20 __version__ =3D '1.0' =20 +app_dir =3D "." + class MaintainersParser: """Parse MAINTAINERS file(s) content""" =20 - def __init__(self, base_path, path): + def __init__(self, path): + global app_dir + self.profile_toc =3D set() self.profile_entries =3D {} =20 @@ -57,6 +66,9 @@ class MaintainersParser: field_content =3D "" subsystem_name =3D None =20 + base_dir, doc_dir, sphinx_dir =3D app_dir.partition("Documentation= ") + print("BASE DIR", base_dir) + for line in open(path): # Have we reached the end of the preformatted Descriptions tex= t? if descriptions and line.startswith('Maintainers'): @@ -76,9 +88,25 @@ class MaintainersParser: # # Handle profile entries - either as files or as https refs # - match =3D re.match(r"P:\s*(Documentation/\S+)\.rst", line) + match =3D re.match(rf"P:\s*({doc_dir})(/\S+)\.rst", line) if match: - entry =3D os.path.relpath(match.group(1), base_path) + 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" + else: + entry =3D "/" + entry + + print(f"{name}: entry: {entry} FULL: {full_name} path: {pa= th}") + if "*" in entry: for e in glob(entry): self.profile_toc.add(e) @@ -189,10 +217,10 @@ class MaintainersInclude(Include): """MaintainersInclude (``maintainers-include``) directive""" required_arguments =3D 0 =20 - def emit(self, base_path, path): + def emit(self, path): """Parse all the MAINTAINERS lines into ReST for human-readability= """ =20 - output =3D MaintainersParser(base_path, path).output + output =3D MaintainersParser(path).output =20 # For debugging the pre-rendered results... #print(output, file=3Dopen("/tmp/MAINTAINERS.rst", "w")) @@ -213,11 +241,10 @@ class MaintainersInclude(Include): =20 # Append "MAINTAINERS" path =3D os.path.join(path, "MAINTAINERS") - base_path =3D os.path.dirname(self.state.document.document.current= _source) =20 try: self.state.document.settings.record_dependencies.add(path) - lines =3D self.emit(base_path, path) + lines =3D self.emit(path) except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) @@ -227,27 +254,20 @@ class MaintainersInclude(Include): class MaintainersProfile(Include): required_arguments =3D 0 =20 - def emit(self, base_path, path): + def emit(self, path): """Parse all the MAINTAINERS lines looking for profile entries""" =20 - maint =3D MaintainersParser(base_path, path) + maint =3D MaintainersParser(path) =20 # # Produce a list with all maintainer profiles, sorted by subsystem= name # output =3D "" - - for profile, entry in maint.profile_entries.items(): + for profile, entry in sorted(maint.profile_entries.items()): if entry.startswith("http"): - if profile: - output +=3D f"- `{profile} <{entry}>`_\n" - else: - output +=3D f"- `<{entry}>_`\n" + output +=3D f"- `{profile} <{entry}>`_\n" else: - if profile: - output +=3D f"- :doc:`{profile} <{entry}>`\n" - else: - output +=3D f"- :doc:`<{entry}>`\n" + output +=3D f"- :doc:`{profile} <{entry}>`\n" =20 # # Create a hidden TOC table with all profiles. That allows adding @@ -261,6 +281,8 @@ class MaintainersProfile(Include): =20 output +=3D "\n" =20 + print(output) + self.state_machine.insert_input(statemachine.string2lines(output),= path) =20 def run(self): @@ -277,11 +299,10 @@ class MaintainersProfile(Include): =20 # Append "MAINTAINERS" path =3D os.path.join(path, "MAINTAINERS") - base_path =3D os.path.dirname(self.state.document.document.current= _source) =20 try: self.state.document.settings.record_dependencies.add(path) - lines =3D self.emit(base_path, path) + lines =3D self.emit(path) except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) @@ -289,6 +310,14 @@ class MaintainersProfile(Include): return [] =20 def setup(app): + global app_dir + + # + # 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) + app.add_directive("maintainers-include", MaintainersInclude) app.add_directive("maintainers-profile-toc", MaintainersProfile) return dict( --=20 2.53.0 From nobody Mon Jun 15 23:14:10 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 0E5BE3D5258; Mon, 27 Apr 2026 14:22:37 +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=1777299757; cv=none; b=paIKeWc9jxFlAkFU2x/Y6yVBkWuVoGmPCIEMnjkoTpg898H536QmxqzODzInIt/b+iMFtGpfxfwCzCMuOiXgmjpGidoe5aa+8uudSb+RiG6CF6pZzjDIeTPsYXpXu1bHMVfh0rAwhrsiN+Ac0PiUDJ97JmILA5cy9PpDLqzhspI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777299757; c=relaxed/simple; bh=eFz8XAM9SiBNlLtIZjPZ85JxZ3rANvBqFGiI57xq6pg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=YKc0MNWXlKddviejbgLDhr+JhnLuj95CC3JvdarWUwkJAw64SP+FSeaZR/NAC2W0RqDb3I8B3l18rDGSXjdmP2qOAMVt3VvlmOTCyeYyQfHaFIHk6a2QVJgvIYDTYkT4YkCYpfcpnDOXUwlI9MKL0N7PqD9SBJ4nyfw5JNSox2c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FDWrdDXh; 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="FDWrdDXh" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D50DFC2BCB4; Mon, 27 Apr 2026 14:22:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777299756; bh=eFz8XAM9SiBNlLtIZjPZ85JxZ3rANvBqFGiI57xq6pg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FDWrdDXhnM9SGHEd65ZvmkRefIelu7R38FBdiVDvQJ4yMfucw7PbvXY0nSEKnt2lS nAQF3TgUG0UT0JvN01L5GLAQRko2eecfKcn9apqpgcfZCxnd973AaiV9W+27u1awe5 nWG+yEc86HL1I2D8H+Ow8Hrug38v3MMdPSk/Ve/qqcrI0v7wDTXaXV4+5TxU30F1+b P/6NedC89m/nr1cvlyXuknfZ2d0QmRubot2bn6R9lLiOk41i5EGBhQdEkIkxRMJLXV UmREdsu4vZtqdcmAjJLSSkWeYnt97EEUODYV9AHdiCVjwdEdnX/+qKtqdLRfwQmmo3 duMRagZlxRWcA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1wHMr5-0000000C8b1-0jdP; Mon, 27 Apr 2026 16:22:35 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Shuah Khan , Randy Dunlap Subject: [PATCH v4 10/10] docs: maintainers_include: parse MAINTAINERS just once Date: Mon, 27 Apr 2026 16:22:28 +0200 Message-ID: <8060589074f54a276e563db8cad124d3f88346c7.1777295258.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Change the logic to parse MAINTAINERS file content just once, while still allowing using it multiple times. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reported-by: Randy Dunlap Suggested-by: Dan Williams --- Documentation/sphinx/maintainers_include.py | 61 +++++++-------------- 1 file changed, 21 insertions(+), 40 deletions(-) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sp= hinx/maintainers_include.py index ae52e8198750..436e7ac42ffc 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -37,14 +37,13 @@ def ErrorString(exc): # Shamelessly stolen from docuti= ls =20 __version__ =3D '1.0' =20 -app_dir =3D "." +maint_parser =3D None =20 class MaintainersParser: """Parse MAINTAINERS file(s) content""" =20 - def __init__(self, path): - global app_dir - + def __init__(self, app_dir, path): + self.path =3D path self.profile_toc =3D set() self.profile_entries =3D {} =20 @@ -67,7 +66,6 @@ class MaintainersParser: subsystem_name =3D None =20 base_dir, doc_dir, sphinx_dir =3D app_dir.partition("Documentation= ") - print("BASE DIR", base_dir) =20 for line in open(path): # Have we reached the end of the preformatted Descriptions tex= t? @@ -105,8 +103,6 @@ class MaintainersParser: else: entry =3D "/" + entry =20 - print(f"{name}: entry: {entry} FULL: {full_name} path: {pa= th}") - if "*" in entry: for e in glob(entry): self.profile_toc.add(e) @@ -217,14 +213,17 @@ class MaintainersInclude(Include): """MaintainersInclude (``maintainers-include``) directive""" required_arguments =3D 0 =20 - def emit(self, path): + def emit(self): """Parse all the MAINTAINERS lines into ReST for human-readability= """ + global maint_parser =20 - output =3D MaintainersParser(path).output + path =3D maint_parser.path + output =3D maint_parser.output =20 # For debugging the pre-rendered results... #print(output, file=3Dopen("/tmp/MAINTAINERS.rst", "w")) =20 + self.state.document.settings.record_dependencies.add(path) self.state_machine.insert_input(statemachine.string2lines(output),= path) =20 def run(self): @@ -232,19 +231,8 @@ class MaintainersInclude(Include): if not self.state.document.settings.file_insertion_enabled: raise self.warning('"%s" directive disabled.' % self.name) =20 - # Walk up source path directories to find Documentation/../ - path =3D self.state_machine.document.attributes['source'] - path =3D os.path.realpath(path) - tail =3D path - while tail !=3D "Documentation" and tail !=3D "": - (path, tail) =3D os.path.split(path) - - # Append "MAINTAINERS" - path =3D os.path.join(path, "MAINTAINERS") - try: - self.state.document.settings.record_dependencies.add(path) - lines =3D self.emit(path) + lines =3D self.emit() except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) @@ -254,16 +242,17 @@ class MaintainersInclude(Include): class MaintainersProfile(Include): required_arguments =3D 0 =20 - def emit(self, path): + def emit(self): """Parse all the MAINTAINERS lines looking for profile entries""" + global maint_parser =20 - maint =3D MaintainersParser(path) + path =3D maint_parser.path =20 # # Produce a list with all maintainer profiles, sorted by subsystem= name # output =3D "" - for profile, entry in sorted(maint.profile_entries.items()): + for profile, entry in sorted(maint_parser.profile_entries.items()): if entry.startswith("http"): output +=3D f"- `{profile} <{entry}>`_\n" else: @@ -276,13 +265,12 @@ class MaintainersProfile(Include): output +=3D "\n.. toctree::\n" output +=3D " :hidden:\n\n" =20 - for fname in maint.profile_toc: + for fname in maint_parser.profile_toc: output +=3D f" {fname}\n" =20 output +=3D "\n" =20 - print(output) - + self.state.document.settings.record_dependencies.add(path) self.state_machine.insert_input(statemachine.string2lines(output),= path) =20 def run(self): @@ -290,19 +278,8 @@ class MaintainersProfile(Include): if not self.state.document.settings.file_insertion_enabled: raise self.warning('"%s" directive disabled.' % self.name) =20 - # Walk up source path directories to find Documentation/../ - path =3D self.state_machine.document.attributes['source'] - path =3D os.path.realpath(path) - tail =3D path - while tail !=3D "Documentation" and tail !=3D "": - (path, tail) =3D os.path.split(path) - - # Append "MAINTAINERS" - path =3D os.path.join(path, "MAINTAINERS") - try: - self.state.document.settings.record_dependencies.add(path) - lines =3D self.emit(path) + lines =3D self.emit() except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) @@ -310,13 +287,17 @@ class MaintainersProfile(Include): return [] =20 def setup(app): - global app_dir + global maint_parser =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") + + maint_parser =3D MaintainersParser(app_dir, path) =20 app.add_directive("maintainers-include", MaintainersInclude) app.add_directive("maintainers-profile-toc", MaintainersProfile) --=20 2.53.0