diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 6020d188e13de1..58e2af333692dc 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 section might also list how review works for this code area and methods to get feedback that are not directly from the maintainer. -Existing profiles ------------------ - -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 +Maintainer Handbooks +-------------------- + +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 3d72ad25fc6acc..3821e78aefc0ab 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -7,14 +7,13 @@ The purpose of this document is to provide subsystem specific information which is supplementary to the general development process handbook :ref:`Documentation/process `. -Contents: +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. -.. toctree:: - :numbered: - :maxdepth: 2 +For maintainers, consider documenting additional requirements and +expectations if submissions routinely overlook specific submission +criteria. See Documentation/maintainer/maintainer-entry-profile.rst. - maintainer-netdev - maintainer-soc - maintainer-soc-clean-dts - maintainer-tip - maintainer-kvm-x86 +.. maintainers-profile-toc:: diff --git a/Documentation/process/maintainers.rst b/Documentation/process/maintainers.rst index 6174cfb4138ffc..5d1b1464c3aeac 100644 --- a/Documentation/process/maintainers.rst +++ b/Documentation/process/maintainers.rst @@ -1 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. maintainers-include:: diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index 519ad18685b23f..436e7ac42ffc0d 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -21,29 +21,31 @@ import re import os.path +from glob import glob + from docutils import statemachine from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include +# +# Base URL for intersphinx-like links to maintainer profiles +# +KERNELDOC_URL = "https://docs.kernel.org/" + def ErrorString(exc): # Shamelessly stolen from docutils return f'{exc.__class__.__name}: {exc}' __version__ = '1.0' -def setup(app): - app.add_directive("maintainers-include", MaintainersInclude) - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) +maint_parser = None -class MaintainersInclude(Include): - """MaintainersInclude (``maintainers-include``) directive""" - required_arguments = 0 +class MaintainersParser: + """Parse MAINTAINERS file(s) content""" - def parse_maintainers(self, path): - """Parse all the MAINTAINERS lines into ReST for human-readability""" + def __init__(self, app_dir, path): + self.path = path + self.profile_toc = set() + self.profile_entries = {} result = list() result.append(".. _maintainers:") @@ -61,6 +63,9 @@ def parse_maintainers(self, path): prev = None field_prev = "" field_content = "" + subsystem_name = None + + base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation") for line in open(path): # Have we reached the end of the preformatted Descriptions text? @@ -78,6 +83,39 @@ def parse_maintainers(self, path): # Drop needless input whitespace. line = line.rstrip() + # + # Handle profile entries - either as files or as https refs + # + match = re.match(rf"P:\s*({doc_dir})(/\S+)\.rst", line) + if match: + name = "".join(match.groups()) + entry = os.path.relpath(base_dir + name, app_dir) + + full_name = os.path.join(base_dir, name) + path = 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 = KERNELDOC_URL + match.group(2) + ".html" + else: + entry = "/" + entry + + if "*" in entry: + for e in glob(entry): + self.profile_toc.add(e) + self.profile_entries[subsystem_name] = e + else: + self.profile_toc.add(entry) + self.profile_entries[subsystem_name] = entry + else: + match = re.match(r"P:\s*(https?://.*)", line) + if match: + entry = match.group(1).strip() + self.profile_entries[subsystem_name] = entry + # Linkify all non-wildcard refs to ReST files in Documentation/. pat = r'(Documentation/([^\s\?\*]*)\.rst)' m = re.search(pat, line) @@ -113,6 +151,8 @@ def parse_maintainers(self, path): output = field_content + "\n\n" field_content = "" + subsystem_name = line.title() + # Collapse whitespace in subsystem name. heading = re.sub(r"\s+", " ", line) output = output + "%s\n%s" % (heading, "~" * len(heading)) @@ -165,33 +205,104 @@ def parse_maintainers(self, path): for separated in field_content.split('\n'): result.append(separated) - output = "\n".join(result) + self.output = "\n".join(result) + + # Create a TOC class + +class MaintainersInclude(Include): + """MaintainersInclude (``maintainers-include``) directive""" + required_arguments = 0 + + def emit(self): + """Parse all the MAINTAINERS lines into ReST for human-readability""" + global maint_parser + + path = maint_parser.path + output = maint_parser.output + # For debugging the pre-rendered results... #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) - self.state_machine.insert_input( - statemachine.string2lines(output), path) + self.state.document.settings.record_dependencies.add(path) + 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 = self.state_machine.document.attributes['source'] - path = os.path.realpath(path) - tail = path - while tail != "Documentation" and tail != "": - (path, tail) = os.path.split(path) + try: + lines = self.emit() + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + return [] + +class MaintainersProfile(Include): + required_arguments = 0 + + def emit(self): + """Parse all the MAINTAINERS lines looking for profile entries""" + global maint_parser + + path = maint_parser.path + + # + # Produce a list with all maintainer profiles, sorted by subsystem name + # + output = "" + for profile, entry in sorted(maint_parser.profile_entries.items()): + if entry.startswith("http"): + output += f"- `{profile} <{entry}>`_\n" + else: + output += f"- :doc:`{profile} <{entry}>`\n" + + # + # Create a hidden TOC table with all profiles. That allows adding + # profiles without needing to add them on any index.rst file. + # + output += "\n.. toctree::\n" + output += " :hidden:\n\n" + + for fname in maint_parser.profile_toc: + output += f" {fname}\n" + + output += "\n" + + self.state.document.settings.record_dependencies.add(path) + self.state_machine.insert_input(statemachine.string2lines(output), path) - # Append "MAINTAINERS" - path = os.path.join(path, "MAINTAINERS") + 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) try: - self.state.document.settings.record_dependencies.add(path) - lines = self.parse_maintainers(path) + lines = self.emit() except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) return [] + +def setup(app): + global maint_parser + + # + # NOTE: we're using os.fspath() here because of a Sphinx warning: + # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead. + # + app_dir = os.fspath(app.srcdir) + srctree = os.path.abspath(os.environ["srctree"]) + path = os.path.join(srctree, "MAINTAINERS") + + maint_parser = MaintainersParser(app_dir, path) + + app.add_directive("maintainers-include", MaintainersInclude) + app.add_directive("maintainers-profile-toc", MaintainersProfile) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) diff --git a/MAINTAINERS b/MAINTAINERS index 2fb1c75afd1638..a00d4ba61c2a85 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -16223,6 +16223,7 @@ P: Documentation/driver-api/media/maintainer-entry-profile.rst W: https://linuxtv.org Q: https://patchwork.linuxtv.org/project/linux-media/list/ T: git git://linuxtv.org/media.git +P: Documentation/driver-api/media/maintainer-entry-profile.rst F: Documentation/admin-guide/media/ F: Documentation/devicetree/bindings/media/ F: Documentation/driver-api/media/ @@ -28807,6 +28808,7 @@ M: Ingo Molnar M: Borislav Petkov M: Dave Hansen M: x86@kernel.org +P: Documentation/process/maintainer-tip.rst R: "H. Peter Anvin" L: linux-kernel@vger.kernel.org S: Maintained