[PATCH 0/9] Improve process/maintainers output

[PATCH 0/9] Improve process/maintainers output

[Mauro Carvalho Chehab]

Hi Jon,

As promised, this series improve the output at process/maintainers:
instead of a pure enriched text, the maintainer's file content is
now converted with a table, and has gained a javascript to allow
filtering entries.

The initial patches change the logic to split parsing from
output generation. Now, everything is stored into a dict at
the parsing phase. This way, it is easier to adjust the
directive handler for it to produce a more structured document.

Right now, the entries are sorted alphabetically, per subsystem's
name.

---

As mentioned before, I did some extra tests here, changing the sort
logic:

- per mailing lists. Easy to do but require a couple of hints;
- per number of files (after using iglob) to calculate the
  actual number of patches. This is fast with NVME, but could
  be slow with HDD.

Doing that helps to group the output per subsytem (assuming
that each major subsystem has its own mailing list), and
placing the subsystem before each entry. Yet, after adding
the JS filter, I'm not sure if it is worth doing it(*).

So, I kept such changes out of the final version.

In any case, with the new logic, changing the output is easy.

(*) Hint: Try setting the <Filter:> box there to linux-doc :-D

    This one is sorted on a nice way, but if you set it to
    linux-media, you'll see that the first entry is Orphan.
    The most relevant one is hidden in the crowd.

-

It should also be easy to add some logic there at the Sphinx
directive to allow, for instance, include per-subsystem
entries, e.g. one could add, in the future, support for
things like:

	.. maintainers-include::
		mailing-list: linux-doc@vger.kernel.org
		sort-by: file-count

And have a page inside the subsystem (Documentation on this
example) with all maintainers per subsystem.

This is just a rough idea. I'm currently not planning to
implement it.


Matteo Croce (1):
  docs: escape ** glob pattern in MAINTAINERS descriptions

Mauro Carvalho Chehab (8):
  docs: maintainers_include: keep hidden TOC sorted
  docs: maintainers_include.py: split state machine on multiple funcs
  docs: maintainers_include: cleanup the code
  docs: maintainers_include.py: clean most SPHINXDIRS=process warnings
  docs: maintainers_include: do some coding style cleanups
  docs: maintainers_include: store maintainers entries on a dict
  docs: maintainers_include: don't ignore invalid profile entries
  docs: maintainers: add a filtering javascript

 Documentation/sphinx/maintainers_include.py | 405 ++++++++++++--------
 1 file changed, 249 insertions(+), 156 deletions(-)

-- 
2.54.0

[PATCH 1/9] docs: maintainers_include: keep hidden TOC sorted

[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 <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 1b9ece431386..c7f9911ae45b 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -265,7 +265,7 @@ class MaintainersProfile(Include):
         output += "\n.. toctree::\n"
         output += "   :hidden:\n\n"
 
-        for fname in maint_parser.profile_toc:
+        for fname in sorted(maint_parser.profile_toc):
             output += f"   {fname}\n"
 
         output += "\n"
-- 
2.54.0

[PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions

[Mauro Carvalho Chehab]

From: Matteo Croce <teknoraver@meta.com>

Escape '**' in the MAINTAINERS descriptions section to prevent
reStructuredText from interpreting it as bold/strong inline markup,
which causes a warning when running 'make htmldocs'.

Fixes: 420849332f9f ("get_maintainer: add ** glob pattern support")
Signed-off-by: Matteo Croce <teknoraver@meta.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index c7f9911ae45b..e679acf0633d 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -127,7 +127,8 @@ class MaintainersParser:
             output = None
             if descriptions:
                 # Escape the escapes in preformatted text.
-                output = "| %s" % (line.replace("\\", "\\\\"))
+                output = "| %s" % (line.replace("\\", "\\\\")
+                                        .replace("**", "\\**"))
                 # Look for and record field letter to field name mappings:
                 #   R: Designated *reviewer*: FullName <address@domain>
                 m = re.search(r"\s(\S):\s", line)
-- 
2.54.0

[PATCH 3/9] docs: maintainers_include.py: split state machine on multiple funcs

[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 <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 299 +++++++++++---------
 1 file changed, 159 insertions(+), 140 deletions(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index e679acf0633d..8867ecc0aad3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -47,168 +47,187 @@ class MaintainersParser:
         self.profile_toc = set()
         self.profile_entries = {}
 
-        result = list()
-        result.append(".. _maintainers:")
-        result.append("")
+        self.output = ".. _maintainers:\n\n"
 
         # Poor man's state machine.
-        descriptions = False
-        maintainers = False
-        subsystems = False
+        self.descriptions = False
+        self.maintainers = False
+        self.subsystems = False
 
         # Field letter to field name mapping.
-        field_letter = None
-        fields = dict()
+        self.field_letter = None
+        self.fields = dict()
+
+        self.field_prev = ""
+        self.field_content = ""
+        self.subsystem_name = None
+
+        self.app_dir = app_dir
+        self.base_dir, self.doc_dir, self.sphinx_dir = app_dir.partition("Documentation")
+
+        self.re_doc = re.compile(r'(Documentation/([^\s\?\*]*)\.rst)')
 
         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?
-            if descriptions and line.startswith('Maintainers'):
-                descriptions = False
-                # Ensure a blank line following the last "|"-prefixed line.
-                result.append("")
-
-            # Start subsystem processing? This is to skip processing the text
-            # 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 = True
-
-            # 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"
+                    self.subsystems = True
+                    self.parse_subsystems(line)
                 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)
-            if m:
-                # maintainers.rst is in a subdirectory, so include "../".
-                line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
-
-            # Check state machine for output rendering behavior.
-            output = None
-            if descriptions:
-                # Escape the escapes in preformatted text.
-                output = "| %s" % (line.replace("\\", "\\\\")
-                                        .replace("**", "\\**"))
-                # Look for and record field letter to field name mappings:
-                #   R: Designated *reviewer*: FullName <address@domain>
-                m = re.search(r"\s(\S):\s", line)
-                if m:
-                    field_letter = m.group(1)
-                if field_letter and not field_letter in fields:
-                    m = re.search(r"\*([^\*]+)\*", line)
-                    if m:
-                        fields[field_letter] = m.group(1)
-            elif subsystems:
-                # Skip empty lines: subsystem parser adds them as needed.
-                if len(line) == 0:
-                    continue
-                # Subsystem fields are batched into "field_content"
-                if line[1] != ':':
-                    # Render a subsystem entry as:
-                    #   SUBSYSTEM NAME
-                    #   ~~~~~~~~~~~~~~
-
-                    # Flush pending field content.
-                    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))
-                    field_prev = ""
-                else:
-                    # Render a subsystem field as:
-                    #   :Field: entry
-                    #           entry...
-                    field, details = line.split(':', 1)
-                    details = 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 = '``%s``' % (details)
-
-                    # Comma separate email field continuations.
-                    if field == field_prev and field_prev in ['M', 'R', 'L']:
-                        field_content = field_content + ","
-
-                    # Do not repeat field names, so that field entries
-                    # will be collapsed together.
-                    if field != field_prev:
-                        output = field_content + "\n"
-                        field_content = ":%s:" % (fields.get(field, field))
-                    field_content = field_content + "\n\t%s" % (details)
-                    field_prev = field
+                    self.output += line
+            elif self.subsystems:
+                self.parse_subsystems(line)
             else:
-                output = line
-
-            # Re-split on any added newlines in any above parsing.
-            if output != None:
-                for separated in output.split('\n'):
-                    result.append(separated)
+                self.output += line
 
             # Update the state machine when we find heading separators.
             if line.startswith('----------'):
                 if prev.startswith('Descriptions'):
-                    descriptions = True
+                    self.descriptions = True
                 if prev.startswith('Maintainers'):
-                    maintainers = True
+                    self.maintainers = True
 
             # Retain previous line for state machine transitions.
             prev = line
 
         # Flush pending field contents.
-        if field_content != "":
-            for separated in field_content.split('\n'):
-                result.append(separated)
+        if self.field_content:
+            self.output += self.field_content + "\n\n"
 
-        self.output = "\n".join(result)
+        self.output = 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 = False
+            self.output += "\n" + line
+            return
+
+        # Linkify all non-wildcard refs to ReST files in Documentation/.
+        m = self.re_doc.search(line)
+        if m:
+            # maintainers.rst is in a subdirectory, so include "../".
+            line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
+
+        # Escape the escapes in preformatted text.
+        output = "| %s" % (line.replace("\\", "\\\\")
+                                .replace("**", "\\**"))
+
+        # Look for and record field letter to field name mappings:
+        #   R: Designated *reviewer*: FullName <address@domain>
+        m = re.search(r"\s(\S):\s", line)
+        if m:
+            self.field_letter = m.group(1)
+
+        if self.field_letter and self.field_letter not in self.fields:
+            m = re.search(r"\*([^\*]+)\*", line)
+            if m:
+                self.fields[self.field_letter] = m.group(1)
+
+        # Append parsed content to self.output
+        self.output += output
+
+    def parse_subsystems(self, line):
+        """Handle contents of the per-subsystem sections."""
+
+        # Drop needless input whitespace.
+        line = line.rstrip()
+
+        #
+        # Handle profile entries - either as files or as https refs
+        #
+        match = re.match(rf"P:\s*({self.doc_dir})(/\S+)\.rst", line)
+        if match:
+            name = "".join(match.groups())
+            entry = os.path.relpath(self.base_dir + name, self.app_dir)
+
+            full_name = os.path.join(self.base_dir, name)
+            path = 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 = 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[self.subsystem_name] = e
+            else:
+                self.profile_toc.add(entry)
+                self.profile_entries[self.subsystem_name] = entry
+        else:
+            match = re.match(r"P:\s*(https?://.*)", line)
+            if match:
+                entry = match.group(1).strip()
+                self.profile_entries[self.subsystem_name] = entry
+
+        # Linkify all non-wildcard refs to ReST files in Documentation/.
+        m = self.re_doc.search(line)
+        if m:
+            # maintainers.rst is in a subdirectory, so include "../".
+            line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
+
+        # Check state machine for output rendering behavior.
+        output = None
+        if self.subsystems:
+            # Skip empty lines: subsystem parser adds them as needed.
+            if len(line) == 0:
+                return
+            # Subsystem fields are batched into "field_content"
+            if line[1] != ':':
+                # Render a subsystem entry as:
+                #   SUBSYSTEM NAME
+                #   ~~~~~~~~~~~~~~
+                # Flush pending field content.
+                output = self.field_content + "\n\n"
+                self.field_content = ""
+
+                self.subsystem_name = line.title()
+
+                # Collapse whitespace in subsystem name.
+                heading = re.sub(r"\s+", " ", line)
+                output = output + "%s\n%s" % (heading, "~" * len(heading))
+                self.field_prev = ""
+            else:
+                # Render a subsystem field as:
+                #   :Field: entry
+                #           entry...
+                field, details = line.split(':', 1)
+                details = 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 = '``%s``' % (details)
+
+                # Comma separate email field continuations.
+                if field == self.field_prev and self.field_prev in ['M', 'R', 'L']:
+                    self.field_content = self.field_content + ","
+
+                # Do not repeat field names, so that field entries
+                # will be collapsed together.
+                if field != self.field_prev:
+                    output = self.field_content + "\n"
+                    self.field_content = ":%s:" % (self.fields.get(field, field))
+                self.field_content = self.field_content + "\n\t%s" % (details)
+                self.field_prev = field
+        elif not self.descriptions:
+            output = line
+
+        if output is not None:
+            self.output += output + "\n"
 
-        # Create a TOC class
 
 class MaintainersInclude(Include):
     """MaintainersInclude (``maintainers-include``) directive"""
-- 
2.54.0

[PATCH 4/9] docs: maintainers_include: cleanup the code

[Mauro Carvalho Chehab]

Simplify the logic without affecting the output result.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 186 ++++++++++----------
 1 file changed, 92 insertions(+), 94 deletions(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 8867ecc0aad3..4fc894b377e6 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -44,10 +44,6 @@ class MaintainersParser:
 
     def __init__(self, app_dir, path):
         self.path = path
-        self.profile_toc = set()
-        self.profile_entries = {}
-
-        self.output = ".. _maintainers:\n\n"
 
         # Poor man's state machine.
         self.descriptions = False
@@ -67,6 +63,13 @@ class MaintainersParser:
 
         self.re_doc = re.compile(r'(Documentation/([^\s\?\*]*)\.rst)')
 
+        #
+        # Output variables with maintainers content to be stored
+        #
+        self.profile_toc = set()
+        self.profile_entries = {}
+        self.output = ".. _maintainers:\n\n"
+
         prev = None
         for line in open(path):
             if self.descriptions:
@@ -98,6 +101,16 @@ class MaintainersParser:
 
         self.output = self.output.rstrip()
 
+
+    def linkify(self, text):
+        """Linkify all non-wildcard refs to ReST files in Documentation/"""
+        m = self.re_doc.search(text)
+        if m:
+            # maintainers.rst is in a subdirectory, so include "../".
+            text = 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."""
 
@@ -107,15 +120,9 @@ class MaintainersParser:
             self.output += "\n" + line
             return
 
-        # Linkify all non-wildcard refs to ReST files in Documentation/.
-        m = self.re_doc.search(line)
-        if m:
-            # maintainers.rst is in a subdirectory, so include "../".
-            line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
-
         # Escape the escapes in preformatted text.
-        output = "| %s" % (line.replace("\\", "\\\\")
-                                .replace("**", "\\**"))
+        line = self.linkify(line).replace("\\", "\\\\").replace("**", "\\**")
+        self.output += "| " + line
 
         # Look for and record field letter to field name mappings:
         #   R: Designated *reviewer*: FullName <address@domain>
@@ -128,105 +135,96 @@ class MaintainersParser:
             if m:
                 self.fields[self.field_letter] = m.group(1)
 
-        # Append parsed content to self.output
-        self.output += output
-
     def parse_subsystems(self, line):
         """Handle contents of the per-subsystem sections."""
 
         # Drop needless input whitespace.
         line = line.rstrip()
 
+        # Skip empty lines: subsystem parser adds them as needed.
+        if not line:
+            return
+
+        # Subsystem fields are batched into "field_content"
+        if line[1] != ':':
+            line = self.linkify(line)
+
+            # Render a subsystem entry as:
+            #   SUBSYSTEM NAME
+            #   ~~~~~~~~~~~~~~
+            # Flush pending field content.
+            self.output += self.field_content + "\n\n"
+            self.field_content = ""
+
+            self.subsystem_name = line.title()
+
+            # Collapse whitespace in subsystem name.
+            heading = re.sub(r"\s+", " ", line)
+            self.output += "%s\n%s" % (heading, "~" * len(heading)) + "\n"
+            self.field_prev = ""
+
+            return
+
+        # Render a subsystem field as:
+        #   :Field: entry
+        #           entry...
+        field, details = line.split(':', 1)
+        details = details.strip()
+
         #
         # Handle profile entries - either as files or as https refs
         #
-        match = re.match(rf"P:\s*({self.doc_dir})(/\S+)\.rst", line)
-        if match:
-            name = "".join(match.groups())
-            entry = os.path.relpath(self.base_dir + name, self.app_dir)
-
-            full_name = os.path.join(self.base_dir, name)
-            path = 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 = 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[self.subsystem_name] = e
-            else:
-                self.profile_toc.add(entry)
-                self.profile_entries[self.subsystem_name] = entry
-        else:
-            match = re.match(r"P:\s*(https?://.*)", line)
+        if field == "P":
+            match = self.re_doc.match(details)
             if match:
-                entry = match.group(1).strip()
-                self.profile_entries[self.subsystem_name] = entry
+                name = "".join(match.groups())
+                entry = os.path.relpath(self.base_dir + name, self.app_dir)
 
-        # Linkify all non-wildcard refs to ReST files in Documentation/.
-        m = self.re_doc.search(line)
-        if m:
-            # maintainers.rst is in a subdirectory, so include "../".
-            line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
+                full_name = os.path.join(self.base_dir, name)
+                path = 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 = KERNELDOC_URL + "/" + match.group(2) + ".html"
+                else:
+                    entry = "/" + entry
 
-        # Check state machine for output rendering behavior.
-        output = None
-        if self.subsystems:
-            # Skip empty lines: subsystem parser adds them as needed.
-            if len(line) == 0:
-                return
-            # Subsystem fields are batched into "field_content"
-            if line[1] != ':':
-                # Render a subsystem entry as:
-                #   SUBSYSTEM NAME
-                #   ~~~~~~~~~~~~~~
-                # Flush pending field content.
-                output = self.field_content + "\n\n"
-                self.field_content = ""
-
-                self.subsystem_name = line.title()
-
-                # Collapse whitespace in subsystem name.
-                heading = re.sub(r"\s+", " ", line)
-                output = output + "%s\n%s" % (heading, "~" * len(heading))
-                self.field_prev = ""
+                if "*" in entry:
+                    for e in glob(entry):
+                        self.profile_toc.add(e)
+                        self.profile_entries[self.subsystem_name] = e
+                else:
+                    self.profile_toc.add(entry)
+                    self.profile_entries[self.subsystem_name] = entry
             else:
-                # Render a subsystem field as:
-                #   :Field: entry
-                #           entry...
-                field, details = line.split(':', 1)
-                details = details.strip()
+                match = re.match(r"(https?://.*)", details)
+                if match:
+                    entry = match.group(1).strip()
+                    self.profile_entries[self.subsystem_name] = entry
 
-                # 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 = '``%s``' % (details)
+        details = self.linkify(details)
 
-                # Comma separate email field continuations.
-                if field == self.field_prev and self.field_prev in ['M', 'R', 'L']:
-                    self.field_content = 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 = '``%s``' % (details)
 
-                # Do not repeat field names, so that field entries
-                # will be collapsed together.
-                if field != self.field_prev:
-                    output = self.field_content + "\n"
-                    self.field_content = ":%s:" % (self.fields.get(field, field))
-                self.field_content = self.field_content + "\n\t%s" % (details)
-                self.field_prev = field
-        elif not self.descriptions:
-            output = line
+        # Comma separate email field continuations.
+        if field == self.field_prev and self.field_prev in ['M', 'R', 'L']:
+            self.field_content = self.field_content + ","
 
-        if output is not None:
-            self.output += output + "\n"
+        # Do not repeat field names, so that field entries
+        # will be collapsed together.
+        if field != self.field_prev:
+            self.output += self.field_content + "\n\n"
+            self.field_content = ":%s:" % (self.fields.get(field, field))
+        self.field_content = self.field_content + "\n\t%s" % (details)
+        self.field_prev = field
 
 
 class MaintainersInclude(Include):
-- 
2.54.0

[PATCH 5/9] docs: maintainers_include.py: clean most SPHINXDIRS=process warnings

[Mauro Carvalho Chehab]

building docs with SPHINXDIRS=process 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 <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 4fc894b377e6..1d7d441e281c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -104,10 +104,27 @@ class MaintainersParser:
 
     def linkify(self, text):
         """Linkify all non-wildcard refs to ReST files in Documentation/"""
+
         m = self.re_doc.search(text)
         if m:
-            # maintainers.rst is in a subdirectory, so include "../".
-            text = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), text)
+            fname = m.group(1)
+            name = m.group(2)
+            ename = "/" + name
+
+            entry = os.path.relpath(self.base_dir + ename, self.app_dir)
+            full_name = os.path.join(self.base_dir, fname)
+            path = os.path.relpath(full_name, self.app_dir)
+
+            #
+            # When SPHINXDIRS is used, it will try to reference files
+            # outside srctree, causing warnings. To avoid that, point
+            # to the latest official documentation
+            #
+            if path.startswith("../"):
+                html = KERNELDOC_URL + m.group(2) + ".html"
+                text = self.re_doc.sub(f'`{name} <{html}>_`', text)
+            else:
+                text = self.re_doc.sub(f':doc:`{name} <{entry}>`', text)
 
         return text
 
-- 
2.54.0

[PATCH 6/9] docs: maintainers_include: do some coding style cleanups

[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 <mchehab+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/sphinx/maintainers_include.py
index 1d7d441e281c..189f22e5fae4 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -1,30 +1,25 @@
 #!/usr/bin/env python
 # SPDX-License-Identifier: GPL-2.0
 # -*- coding: utf-8; mode: python -*-
-# pylint: disable=R0903, C0330, R0914, R0912, E0401
+# pylint: disable=C0209, C0301, E0401, R0022, R0902, R0903, R0912, R0914
 
 """
-    maintainers-include
-    ~~~~~~~~~~~~~~~~~~~
+Implementation of the ``maintainers-include`` reST-directive.
 
-    Implementation of the ``maintainers-include`` reST-directive.
+:copyright:  Copyright (C) 2019  Kees Cook <keescook@chromium.org>
+:license:    GPL Version 2, June 1991 see linux/COPYING for details.
 
-    :copyright:  Copyright (C) 2019  Kees Cook <keescook@chromium.org>
-    :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.
 """
 
-import sys
-import re
 import os.path
+import re
 
 from glob import glob
 
 from docutils import statemachine
-from docutils.parsers.rst import Directive
 from docutils.parsers.rst.directives.misc import Include
 
 #
@@ -32,12 +27,14 @@ from docutils.parsers.rst.directives.misc import Include
 #
 KERNELDOC_URL = "https://docs.kernel.org/"
 
-def ErrorString(exc):  # Shamelessly stolen from docutils
-    return f'{exc.__class__.__name}: {exc}'
+__version__ = "1.0"
 
-__version__  = '1.0'
+maint_parser = None  # pylint: disable=C0103
 
-maint_parser = None
+
+# Shamelessly stolen from docutils
+def ErrorString(exc):  # pylint: disable=C0103, C0116
+    return f"{exc.__class__.__name}: {exc}"  # pylint: disable=W0212
 
 class MaintainersParser:
     """Parse MAINTAINERS file(s) content"""
@@ -52,7 +49,7 @@ class MaintainersParser:
 
         # Field letter to field name mapping.
         self.field_letter = None
-        self.fields = dict()
+        self.fields = {}
 
         self.field_prev = ""
         self.field_content = ""
@@ -71,29 +68,30 @@ class MaintainersParser:
         self.output = ".. _maintainers:\n\n"
 
         prev = 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 = True
+        with open(path, "r", encoding="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 = True
+                        self.parse_subsystems(line)
+                    else:
+                        self.output += line
+                elif self.subsystems:
                     self.parse_subsystems(line)
                 else:
                     self.output += line
-            elif self.subsystems:
-                self.parse_subsystems(line)
-            else:
-                self.output += line
 
-            # Update the state machine when we find heading separators.
-            if line.startswith('----------'):
-                if prev.startswith('Descriptions'):
-                    self.descriptions = True
-                if prev.startswith('Maintainers'):
-                    self.maintainers = True
+                # Update the state machine when we find heading separators.
+                if line.startswith("----------"):
+                    if prev.startswith("Descriptions"):
+                        self.descriptions = True
+                    if prev.startswith("Maintainers"):
+                        self.maintainers = True
 
-            # Retain previous line for state machine transitions.
-            prev = line
+                # Retain previous line for state machine transitions.
+                prev = line
 
         # Flush pending field contents.
         if self.field_content:
@@ -132,7 +130,7 @@ class MaintainersParser:
         """Handle contents of the descriptions section."""
 
         # Have we reached the end of the preformatted Descriptions text?
-        if line.startswith('Maintainers'):
+        if line.startswith("Maintainers"):
             self.descriptions = False
             self.output += "\n" + line
             return
@@ -185,7 +183,7 @@ class MaintainersParser:
         # Render a subsystem field as:
         #   :Field: entry
         #           entry...
-        field, details = line.split(':', 1)
+        field, details = line.split(":", 1)
         details = details.strip()
 
         #
@@ -246,12 +244,11 @@ class MaintainersParser:
 
 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
 
@@ -267,20 +264,21 @@ class MaintainersInclude(Include):
             raise self.warning('"%s" directive disabled.' % self.name)
 
         try:
-            lines = self.emit()
+            self.emit()
         except IOError as error:
             raise self.severe('Problems with "%s" directive path:\n%s.' %
                       (self.name, ErrorString(error)))
 
         return []
 
+
 class MaintainersProfile(Include):
+    """Generate a list with all maintainer's profiles"""
+
     required_arguments = 0
 
     def emit(self):
         """Parse all the MAINTAINERS lines looking for profile entries"""
-        global maint_parser
-
         path = maint_parser.path
 
         #
@@ -317,15 +315,17 @@ class MaintainersProfile(Include):
             raise self.warning('"%s" directive disabled.' % self.name)
 
         try:
-            lines = self.emit()
+            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
+    """Setup Sphinx exension"""
+    global maint_parser  # pylint: disable=W0603
 
     #
     # NOTE: we're using os.fspath() here because of a Sphinx warning:
@@ -339,8 +339,9 @@ def setup(app):
 
     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
-    )
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
-- 
2.54.0

[PATCH 7/9] docs: maintainers_include: store maintainers entries on a dict

[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 <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 82 +++++++++------------
 1 file changed, 35 insertions(+), 47 deletions(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 189f22e5fae4..50359b125db0 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -49,10 +49,7 @@ class MaintainersParser:
 
         # Field letter to field name mapping.
         self.field_letter = None
-        self.fields = {}
 
-        self.field_prev = ""
-        self.field_content = ""
         self.subsystem_name = None
 
         self.app_dir = app_dir
@@ -65,7 +62,9 @@ class MaintainersParser:
         #
         self.profile_toc = set()
         self.profile_entries = {}
-        self.output = ".. _maintainers:\n\n"
+        self.header = ".. _maintainers:\n\n"
+        self.maint_entries = {}
+        self.fields = {}
 
         prev = None
         with open(path, "r", encoding="utf-8") as fp:
@@ -77,11 +76,11 @@ class MaintainersParser:
                         self.subsystems = True
                         self.parse_subsystems(line)
                     else:
-                        self.output += line
+                        self.header += line
                 elif self.subsystems:
                     self.parse_subsystems(line)
                 else:
-                    self.output += line
+                    self.header += line
 
                 # 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 = line
 
-        # Flush pending field contents.
-        if self.field_content:
-            self.output += self.field_content + "\n\n"
-
-        self.output = self.output.rstrip()
-
-
     def linkify(self, text):
         """Linkify all non-wildcard refs to ReST files in Documentation/"""
 
@@ -132,12 +124,12 @@ class MaintainersParser:
         # Have we reached the end of the preformatted Descriptions text?
         if line.startswith("Maintainers"):
             self.descriptions = False
-            self.output += "\n" + line
+            self.header += "\n" + line
             return
 
         # Escape the escapes in preformatted text.
         line = self.linkify(line).replace("\\", "\\\\").replace("**", "\\**")
-        self.output += "| " + line
+        self.header += "| " + line
 
         # Look for and record field letter to field name mappings:
         #   R: Designated *reviewer*: FullName <address@domain>
@@ -160,24 +152,8 @@ class MaintainersParser:
         if not line:
             return
 
-        # Subsystem fields are batched into "field_content"
         if line[1] != ':':
-            line = self.linkify(line)
-
-            # Render a subsystem entry as:
-            #   SUBSYSTEM NAME
-            #   ~~~~~~~~~~~~~~
-            # Flush pending field content.
-            self.output += self.field_content + "\n\n"
-            self.field_content = ""
-
-            self.subsystem_name = line.title()
-
-            # Collapse whitespace in subsystem name.
-            heading = re.sub(r"\s+", " ", line)
-            self.output += "%s\n%s" % (heading, "~" * len(heading)) + "\n"
-            self.field_prev = ""
-
+            self.subsystem_name = re.sub(r"\s+", " ", self.linkify(line))
             return
 
         # Render a subsystem field as:
@@ -192,20 +168,22 @@ class MaintainersParser:
         if field == "P":
             match = self.re_doc.match(details)
             if match:
-                name = "".join(match.groups())
-                entry = os.path.relpath(self.base_dir + name, self.app_dir)
+                fname = match.group(1)
+                ename = "/" + match.group(2)
 
-                full_name = os.path.join(self.base_dir, name)
+                entry = os.path.relpath(self.base_dir + ename, self.app_dir)
+                full_name = os.path.join(self.base_dir, fname)
                 path = 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 = KERNELDOC_URL + "/" + match.group(2) + ".html"
+                    entry = KERNELDOC_URL + fname + ".html"
                 else:
-                    entry = "/" + entry
+                    entry = ename
 
                 if "*" in entry:
                     for e in glob(entry):
@@ -222,23 +200,23 @@ class MaintainersParser:
 
         details = self.linkify(details)
 
+        #
         # 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 = '``%s``' % (details)
 
-        # Comma separate email field continuations.
-        if field == self.field_prev and self.field_prev in ['M', 'R', 'L']:
-            self.field_content = self.field_content + ","
+        if self.subsystem_name not in self.maint_entries:
+            self.maint_entries[self.subsystem_name] = {}
+
+        if field not in self.maint_entries[self.subsystem_name]:
+            self.maint_entries[self.subsystem_name][field] = []
+
+        self.maint_entries[self.subsystem_name][field].append(details)
 
-        # Do not repeat field names, so that field entries
-        # will be collapsed together.
-        if field != self.field_prev:
-            self.output += self.field_content + "\n\n"
-            self.field_content = ":%s:" % (self.fields.get(field, field))
-        self.field_content = self.field_content + "\n\t%s" % (details)
         self.field_prev = field
 
 
@@ -250,7 +228,15 @@ class MaintainersInclude(Include):
     def emit(self):
         """Parse all the MAINTAINERS lines into ReST for human-readability"""
         path = maint_parser.path
-        output = maint_parser.output
+        output = maint_parser.header
+
+        for name, fields in maint_parser.maint_entries.items():
+            output += "\n" + name + "\n"
+            output += "~" * len(name) + "\n"
+
+            for field, lines in fields.items():
+                field_name = maint_parser.fields.get(field, field)
+                output += f":{field_name}:\n\t" + ",\n\t".join(lines) + "\n\n"
 
         # For debugging the pre-rendered results...
         print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -286,6 +272,8 @@ class MaintainersProfile(Include):
         #
         output = ""
         for profile, entry in sorted(maint_parser.profile_entries.items()):
+            profile = profile.title()
+
             if entry.startswith("http"):
                 output += f"- `{profile} <{entry}>`_\n"
             else:
-- 
2.54.0

[PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Mauro Carvalho Chehab]

Currently, there is a "P" entry for Rust pin-point that is
neither a valid ReST file nor an hyperlink. While the real
fix there would be to ensure that the documentation can be
properly seen at documentation, add a logic to handle it as
a file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 50359b125db0..bbdadf2aa4f3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -197,6 +197,8 @@ class MaintainersParser:
                 if match:
                     entry = match.group(1).strip()
                     self.profile_entries[self.subsystem_name] = entry
+                else:
+                    self.profile_entries[self.subsystem_name] = f"``{details}``"
 
         details = self.linkify(details)
 
@@ -276,6 +278,8 @@ class MaintainersProfile(Include):
 
             if entry.startswith("http"):
                 output += f"- `{profile} <{entry}>`_\n"
+            elif entry.startswith("`"):
+                output += f"- {profile}: {entry}\n"
             else:
                 output += f"- :doc:`{profile} <{entry}>`\n"
 
-- 
2.54.0

[PATCH 9/9] docs: maintainers: add a filtering javascript

[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 <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/maintainers_include.py | 77 +++++++++++++++++++--
 1 file changed, 71 insertions(+), 6 deletions(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index bbdadf2aa4f3..f85298627da2 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -31,6 +31,48 @@ __version__ = "1.0"
 
 maint_parser = None  # pylint: disable=C0103
 
+JS_FILTER = """
+(function() {
+  function filterTable(table) {
+    const filter = document.getElementById("filter-table").value.trim();
+    const rows = table.querySelectorAll("tbody tr");
+    for (let i = 0; i < rows.length; i++) {
+      const tds = rows[i].getElementsByTagName("td");
+      let match = false;
+      for (let j = 0; j < tds.length; j++) {
+        const cellText = (tds[j].textContent || tds[j].innerText);
+        if (cellText.includes(filter)) {
+          match = true;
+          break;
+        }
+      }
+      rows[i].style.display = match ? "table-row" : "none";
+    }
+  }
+  function addInput() {
+    const table = document.getElementById("maintainers-table");
+    if (!table) return;
+    let input = document.getElementById("filter-table");
+    if (!input) {
+      const filt_div = document.createElement('div');
+      filt_div.innerHTML = `
+        <p>Filter:
+          <input type="search" id="filter-table" placeholder="subsystem or property (case-sensitive)" />
+        </p>
+      `;
+      table.parentNode.insertBefore(filt_div, table);
+      const input = document.getElementById("filter-table")
+      input.addEventListener('input', () => filterTable(table));
+    }
+  }
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', addInput);
+  } else {
+    addInput();
+  }
+})();
+"""
+
 
 # Shamelessly stolen from docutils
 def ErrorString(exc):  # pylint: disable=C0103, C0116
@@ -62,7 +104,7 @@ class MaintainersParser:
         #
         self.profile_toc = set()
         self.profile_entries = {}
-        self.header = ".. _maintainers:\n\n"
+        self.header = ""
         self.maint_entries = {}
         self.fields = {}
 
@@ -230,15 +272,28 @@ class MaintainersInclude(Include):
     def emit(self):
         """Parse all the MAINTAINERS lines into ReST for human-readability"""
         path = maint_parser.path
-        output = maint_parser.header
+        output = ".. _maintainers:\n\n"
+        output += maint_parser.header
+
+        output += ".. _maintainers_table:\n\n"
+        output += ".. flat-table::\n"
+        output += "  :header-rows: 1\n\n"
+        output += "  * - Subsystem\n"
+        output += "    - Properties\n\n"
+
+        self.state.document['maintainers_included'] = True
 
         for name, fields in maint_parser.maint_entries.items():
-            output += "\n" + name + "\n"
-            output += "~" * len(name) + "\n"
-
+            output += f"  * - {name}\n"
+            tag = "-"
             for field, lines in fields.items():
                 field_name = maint_parser.fields.get(field, field)
-                output += f":{field_name}:\n\t" + ",\n\t".join(lines) + "\n\n"
+
+                output += f"    {tag} :{field_name}:\n        "
+                output += ",\n        ".join(lines) + "\n"
+                tag = " "
+
+            output += "\n"
 
         # For debugging the pre-rendered results...
         print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -315,6 +370,14 @@ class MaintainersProfile(Include):
         return []
 
 
+# pylint: disable=W0613
+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=JS_FILTER)
+
+
 def setup(app):
     """Setup Sphinx exension"""
     global maint_parser  # pylint: disable=W0603
@@ -332,6 +395,8 @@ def setup(app):
     app.add_directive("maintainers-include", MaintainersInclude)
     app.add_directive("maintainers-profile-toc", MaintainersProfile)
 
+    app.connect("html-page-context", add_filter_script)
+
     return {
         "version": __version__,
         "parallel_read_safe": True,
-- 
2.54.0

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Miguel Ojeda]

On Mon, May 4, 2026 at 5:51 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Currently, there is a "P" entry for Rust pin-point that is
> neither a valid ReST file nor an hyperlink. While the real

I guess you mean pin-init above, i.e. this entry:

    P: rust/pin-init/CONTRIBUTING.md

It would be nice to clarify it in the commit message that it refers to
a file (which is allowed for `P:` entries according to the docs).

And, yeah, ideally we could make it a hyperlink to the raw file.

Thanks!

Cheers,
Miguel

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Mauro Carvalho Chehab]

On Mon, 4 May 2026 18:08:06 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Mon, May 4, 2026 at 5:51 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Currently, there is a "P" entry for Rust pin-point that is
> > neither a valid ReST file nor an hyperlink. While the real  
> 
> I guess you mean pin-init above, i.e. this entry:
> 
>     P: rust/pin-init/CONTRIBUTING.md
> 
> It would be nice to clarify it in the commit message that it refers to
> a file (which is allowed for `P:` entries according to the docs).

It is not written there, but by file, it would actually be expected
a file within Documentation in ReST format ;-)

> And, yeah, ideally we could make it a hyperlink to the raw file.

I'm afraid that this is not possible. Sphinx doesn't allow
hyperlinks to point to files outside the documentation root
(which is Documentation/ when SPHINXDIRS is not used).

IMO the best would be to run:

	pandoc -i rust/pin-init/CONTRIBUTING.md -t rst -o Documentation/rust/pin-init-profile.rst
	sed s,rust/pin-init/CONTRIBUTING.md,Documentation/rust/pin-init-profile.rst, -i MAINTAINERS

This way, it will generate a proper hyperlink.

Thanks,
Mauro

Re: [PATCH 9/9] docs: maintainers: add a filtering javascript

[Randy Dunlap]

On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> 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 <mchehab+huawei@kernel.org>
> ---
>  Documentation/sphinx/maintainers_include.py | 77 +++++++++++++++++++--
>  1 file changed, 71 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
> index bbdadf2aa4f3..f85298627da2 100755
> --- a/Documentation/sphinx/maintainers_include.py
> +++ b/Documentation/sphinx/maintainers_include.py

> +  function addInput() {
> +    const table = document.getElementById("maintainers-table");
> +    if (!table) return;
> +    let input = document.getElementById("filter-table");
> +    if (!input) {
> +      const filt_div = document.createElement('div');
> +      filt_div.innerHTML = `
> +        <p>Filter:
> +          <input type="search" id="filter-table" placeholder="subsystem or property (case-sensitive)" />

The "placeholder" string does not fit inside the prompt/entry block so it is
truncated with no way to tell what the missing part is AFAICT.
Maybe include that after "Filter:"? E.g.,

           <p>Filter: (subsystem or property, case-sensitive)

> +        </p>
> +      `;


-- 
~Randy

Re: [PATCH 0/9] Improve process/maintainers output

[Randy Dunlap]

On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> Hi Jon,
> 
> As promised, this series improve the output at process/maintainers:
> instead of a pure enriched text, the maintainer's file content is
> now converted with a table, and has gained a javascript to allow
> filtering entries.
> 
> The initial patches change the logic to split parsing from
> output generation. Now, everything is stored into a dict at
> the parsing phase. This way, it is easier to adjust the
> directive handler for it to produce a more structured document.
> 
> Right now, the entries are sorted alphabetically, per subsystem's
> name.

How is subsystem determined? Just by the heading?
The MAINTAINERS file doesn't stay sorted so the output isn't sorted
unless I am just missing something basic.

See e.g.:
DRM TTM SUBSYSTEM
GPU BUDDY ALLOCATOR
DRM AUTOMATED TESTING


-- 
~Randy

Re: [PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions

[Randy Dunlap]

On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> From: Matteo Croce <teknoraver@meta.com>
> 
> Escape '**' in the MAINTAINERS descriptions section to prevent
> reStructuredText from interpreting it as bold/strong inline markup,
> which causes a warning when running 'make htmldocs'.
> 
> Fixes: 420849332f9f ("get_maintainer: add ** glob pattern support")
> Signed-off-by: Matteo Croce <teknoraver@meta.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/sphinx/maintainers_include.py | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
> index c7f9911ae45b..e679acf0633d 100755
> --- a/Documentation/sphinx/maintainers_include.py
> +++ b/Documentation/sphinx/maintainers_include.py
> @@ -127,7 +127,8 @@ class MaintainersParser:
>              output = None
>              if descriptions:
>                  # Escape the escapes in preformatted text.
> -                output = "| %s" % (line.replace("\\", "\\\\"))
> +                output = "| %s" % (line.replace("\\", "\\\\")
> +                                        .replace("**", "\\**"))
>                  # Look for and record field letter to field name mappings:
>                  #   R: Designated *reviewer*: FullName <address@domain>
>                  m = re.search(r"\s(\S):\s", line)

These comments still apply from my review of this patch on 4/9/26:

It's nice to eliminate one warning from 'make htmldocs', so this is good
in that regard. However, there are still multiple problems (not Warnings)
with '*' characters in the MAINTAINERS file:

1) 	   F:	*/net/*		all files in "any top level directory"/net

In the html output, it shows "/net/" italicized (that's what one * does).

2)	   F:	fs/**/*foo*.c	all *foo*.c files in any subdirectory of fs

In the html output, it shows

	F: fs/**/foo.c all foo.c files in any subdirectory of fs

with both occurrences of "foo.c" italicized (dropping the '*' characters).

These 2 examples are actively wrong.

[adding new:]
We would be better served by just putting file patterns inside ``fs/**/*foo*.c``
quotation marks IMO.

Ah, similar to what you do in the table output.

Oh, with one little glitch:
E.g., in the very first entry for 3C59X NETWORK DRIVER,
  F:	Documentation/networking/device_drivers/ethernet/3com/vortex.rst
  F:	drivers/net/ethernet/3com/3c59x.c
it looks like automarkup is applied to the Documentation file so these
2 files are displayed as:

networking/device_drivers/ethernet/3com/vortex, drivers/net/ethernet/3com/3c59x.c

with the Doc file underlined and missing both Documentation and .rst.
Or maybe that's what you intended since the automarkup link does work.
It's just not what I expected. Oh well.


-- 
~Randy

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Gary Guo]

On Mon May 4, 2026 at 9:26 PM BST, Mauro Carvalho Chehab wrote:
> On Mon, 4 May 2026 18:08:06 +0200
> Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
>
>> On Mon, May 4, 2026 at 5:51 PM Mauro Carvalho Chehab
>> <mchehab+huawei@kernel.org> wrote:
>> >
>> > Currently, there is a "P" entry for Rust pin-point that is

I suppose the commit message is supposed to refer to pin-init instead of
pin-point?

>> > neither a valid ReST file nor an hyperlink. While the real  
>> 
>> I guess you mean pin-init above, i.e. this entry:
>> 
>>     P: rust/pin-init/CONTRIBUTING.md
>> 
>> It would be nice to clarify it in the commit message that it refers to
>> a file (which is allowed for `P:` entries according to the docs).
>
> It is not written there, but by file, it would actually be expected
> a file within Documentation in ReST format ;-)
>
>> And, yeah, ideally we could make it a hyperlink to the raw file.
>
> I'm afraid that this is not possible. Sphinx doesn't allow
> hyperlinks to point to files outside the documentation root
> (which is Documentation/ when SPHINXDIRS is not used).

I suppose we can just change it to a link to the render doc on GitHub.

We already mentioned in that contributing file that pin-init changes ideally go
via GitHub (and then patches are synced to kernel) as this is a library and we
have extensive test suite on compiler error message / test on macro expansion which
cannot be integrated with kernel tooling. So changing the P entry from a in-tree
file to URL shouldn't really be an issue.

Best,
Gary

>
> IMO the best would be to run:
>
> 	pandoc -i rust/pin-init/CONTRIBUTING.md -t rst -o Documentation/rust/pin-init-profile.rst
> 	sed s,rust/pin-init/CONTRIBUTING.md,Documentation/rust/pin-init-profile.rst, -i MAINTAINERS
>
> This way, it will generate a proper hyperlink.
>
> Thanks,
> Mauro

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Mauro Carvalho Chehab]

On Mon, 04 May 2026 23:37:38 +0100
"Gary Guo" <gary@garyguo.net> wrote:

> On Mon May 4, 2026 at 9:26 PM BST, Mauro Carvalho Chehab wrote:
> > On Mon, 4 May 2026 18:08:06 +0200
> > Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
> >  
> >> On Mon, May 4, 2026 at 5:51 PM Mauro Carvalho Chehab
> >> <mchehab+huawei@kernel.org> wrote:  
> >> >
> >> > Currently, there is a "P" entry for Rust pin-point that is  
> 
> I suppose the commit message is supposed to refer to pin-init instead of
> pin-point?

Gah, sorry for the typo!

I'll fix on a next version.

> >> > neither a valid ReST file nor an hyperlink. While the real    
> >> 
> >> I guess you mean pin-init above, i.e. this entry:
> >> 
> >>     P: rust/pin-init/CONTRIBUTING.md
> >> 
> >> It would be nice to clarify it in the commit message that it refers to
> >> a file (which is allowed for `P:` entries according to the docs).  
> >
> > It is not written there, but by file, it would actually be expected
> > a file within Documentation in ReST format ;-)
> >  
> >> And, yeah, ideally we could make it a hyperlink to the raw file.  
> >
> > I'm afraid that this is not possible. Sphinx doesn't allow
> > hyperlinks to point to files outside the documentation root
> > (which is Documentation/ when SPHINXDIRS is not used).  
> 
> I suppose we can just change it to a link to the render doc on GitHub.

This works too: there are other P: entries like that pointing to an
external URL that was rendered somehow.

That's said, GitHub (and, AFAIKT GitLab) supports both Markdown and
ReStructured Text. So, if one wants to keep the file on both places,
rst is a common denominator.

> We already mentioned in that contributing file that pin-init changes ideally go
> via GitHub (and then patches are synced to kernel) as this is a library and we
> have extensive test suite on compiler error message / test on macro expansion which
> cannot be integrated with kernel tooling. So changing the P entry from a in-tree
> file to URL shouldn't really be an issue.

Works for me.

> Best,
> Gary
> 
> >
> > IMO the best would be to run:
> >
> > 	pandoc -i rust/pin-init/CONTRIBUTING.md -t rst -o Documentation/rust/pin-init-profile.rst
> > 	sed s,rust/pin-init/CONTRIBUTING.md,Documentation/rust/pin-init-profile.rst, -i MAINTAINERS
> >
> > This way, it will generate a proper hyperlink.
> >
> > Thanks,
> > Mauro  
> 



Thanks,
Mauro

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Miguel Ojeda]

On Mon, May 4, 2026 at 10:26 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> It is not written there, but by file, it would actually be expected
> a file within Documentation in ReST format ;-)

I don't know! :)

You are right that we encourage rst in Doc/, but for vendored stuff,
it makes sense to allow other paths (and other formats).

> I'm afraid that this is not possible. Sphinx doesn't allow
> hyperlinks to point to files outside the documentation root
> (which is Documentation/ when SPHINXDIRS is not used).

Hmm... That could actually be useful for other things (e.g. links to
particular source files).

> IMO the best would be to run:
>
>         pandoc -i rust/pin-init/CONTRIBUTING.md -t rst -o Documentation/rust/pin-init-profile.rst
>         sed s,rust/pin-init/CONTRIBUTING.md,Documentation/rust/pin-init-profile.rst, -i MAINTAINERS
>
> This way, it will generate a proper hyperlink.

You mean on the fly, or committing it?

If you mean committing, then I think it would be best to avoid
modifying vendored files.

If you mean on the fly, then that could actually be quite interesting,
and we recently discussed e.g. whether to have a particular file in
.md vs .rst and whether we could handle the conversion out-of-tree
just for that reason. So if it could be done in-tree, even better. But
pandoc is a heavy dependency to request, no?

Cheers,
Miguel

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Mauro Carvalho Chehab]

On Tue, 5 May 2026 01:34:55 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Mon, May 4, 2026 at 10:26 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > It is not written there, but by file, it would actually be expected
> > a file within Documentation in ReST format ;-)  
> 
> I don't know! :)
> 
> You are right that we encourage rst in Doc/, but for vendored stuff,
> it makes sense to allow other paths (and other formats).
> 
> > I'm afraid that this is not possible. Sphinx doesn't allow
> > hyperlinks to point to files outside the documentation root
> > (which is Documentation/ when SPHINXDIRS is not used).  
> 
> Hmm... That could actually be useful for other things (e.g. links to
> particular source files).

I know but this is part of Sphinx logic to protect against dir
traversal. We added an include extension to allow including
source files, but it will still require a file inside Documentation.

As a general rule, all files generated at Sphinx output directory
needs a source file inside Documentation/ directory.

> 
> > IMO the best would be to run:
> >
> >         pandoc -i rust/pin-init/CONTRIBUTING.md -t rst -o Documentation/rust/pin-init-profile.rst
> >         sed s,rust/pin-init/CONTRIBUTING.md,Documentation/rust/pin-init-profile.rst, -i MAINTAINERS
> >
> > This way, it will generate a proper hyperlink.  
> 
> You mean on the fly, or committing it?

I meant committing it.

> If you mean committing, then I think it would be best to avoid
> modifying vendored files.

Not sure what you meant by "vendored files". Maintainer's profile
is not something where vendors are the only ones ruling it. Instead,
it has to be aligned with the Kernel development process and Kernel
maintainers, independently if they're working on a particular
vendor or not.

Also, with time, maintainers may change their employers while still 
keeping their maintainership status.

So, I'd say that whatever is there at the "P" entry, or where it is
located (either on a ReST file at the Kernel or on some external URL),
it should reflect the model that a maintainer or subsystem community 
that actively participate at the Kernel development agrees with.
This should be vendor-agnostic.

> If you mean on the fly, then that could actually be quite interesting,
> and we recently discussed e.g. whether to have a particular file in
> .md vs .rst and whether we could handle the conversion out-of-tree
> just for that reason. So if it could be done in-tree, even better. 

Generating on the fly is a bad idea, as when one uses:

	make O=SOME_DIR

It is expected that the original source directory will remain
untouched. 

> But pandoc is a heavy dependency to request, no?

I suggested pandoc as a one-time conversion if one wants to migrate
from MD to rst, as for simple documents like this one, it works
fine. 

In summary, I can see 3 possible alternatives to have the Kernel
generated documentation to have a link to the profile:

1. convert it from MD to RST and keep only at the Kernel, inside
   Documentation/;
2. convert it from MD to RST and keep both at the Kernel and at
   Gitlab/Github (both supports .rst files natively);
3. change the "P" entry to point to an external URL.

Regards,
Mauro

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Miguel Ojeda]

On Tue, May 5, 2026 at 2:08 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Also, with time, maintainers may change their employers while still
> keeping their maintainership status.
>
> So, I'd say that whatever is there at the "P" entry, or where it is
> located (either on a ReST file at the Kernel or on some external URL),
> it should reflect the model that a maintainer or subsystem community
> that actively participate at the Kernel development agrees with.
> This should be vendor-agnostic.

I am not sure what you mean. By "vendored" I don't mean
companies/employers, I mean that the file comes from an upstream
repository:

  https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md

Nevertheless, it is true that this really is a special case, in that
the upstream project decided to provide something that could then be
fit into the `P:` field.

One could say "let's ask them to do rst upstream", but to be honest,
it is simpler to just put a hyperlink to GitHub's rendered file.
Markdown is anyway a better fit for their file.

> Generating on the fly is a bad idea, as when one uses:
>
>         make O=SOME_DIR
>
> It is expected that the original source directory will remain
> untouched.

I am not sure why that would be a problem -- the output would be in
`objtree`, not in `srctree`, as usual.

> I suggested pandoc as a one-time conversion if one wants to migrate
> from MD to rst, as for simple documents like this one, it works
> fine.

They are the maintainers, so it is up to them, but it is simpler to
use a hyperlink.

(The file is trivial, i.e. the conversion can be done in a moment
without `pandoc`).

Cheers,
Miguel

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Gary Guo]

On Tue May 5, 2026 at 12:23 AM BST, Mauro Carvalho Chehab wrote:
> On Mon, 04 May 2026 23:37:38 +0100
> "Gary Guo" <gary@garyguo.net> wrote:
>
>> On Mon May 4, 2026 at 9:26 PM BST, Mauro Carvalho Chehab wrote:
>> > On Mon, 4 May 2026 18:08:06 +0200
>> > Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
>> >  
>> >> On Mon, May 4, 2026 at 5:51 PM Mauro Carvalho Chehab
>> >> <mchehab+huawei@kernel.org> wrote:  
>> >> >
>> >> > Currently, there is a "P" entry for Rust pin-point that is  
>> 
>> I suppose the commit message is supposed to refer to pin-init instead of
>> pin-point?
>
> Gah, sorry for the typo!
>
> I'll fix on a next version.
>
>> >> > neither a valid ReST file nor an hyperlink. While the real    
>> >> 
>> >> I guess you mean pin-init above, i.e. this entry:
>> >> 
>> >>     P: rust/pin-init/CONTRIBUTING.md
>> >> 
>> >> It would be nice to clarify it in the commit message that it refers to
>> >> a file (which is allowed for `P:` entries according to the docs).  
>> >
>> > It is not written there, but by file, it would actually be expected
>> > a file within Documentation in ReST format ;-)
>> >  
>> >> And, yeah, ideally we could make it a hyperlink to the raw file.  
>> >
>> > I'm afraid that this is not possible. Sphinx doesn't allow
>> > hyperlinks to point to files outside the documentation root
>> > (which is Documentation/ when SPHINXDIRS is not used).  
>> 
>> I suppose we can just change it to a link to the render doc on GitHub.
>
> This works too: there are other P: entries like that pointing to an
> external URL that was rendered somehow.
>
> That's said, GitHub (and, AFAIKT GitLab) supports both Markdown and
> ReStructured Text. So, if one wants to keep the file on both places,
> rst is a common denominator.

Unfortunately that'll create some internal inconsistency for pin-init as we'd
have a CONTRIBUTING.rst next to a README.md. The README has to have markdown
format as we have some code samples that's shared with Rust crate documentation
which needs to be Markdown.

Doing conversions could work, but it feels too much hassle for a single P: entry
so I'd rather just change it to the external link. (Also it'll have a chance of
getting out of sync, especially if conversions are not loseless and they cannot
round-trip, which I suppose is likely).

Best,
Gary

Re: [PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions

[Joe Perches]

On Mon, 2026-05-04 at 14:20 -0700, Randy Dunlap wrote:
> On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> From: Matteo Croce <[teknoraver@meta.com](mailto:teknoraver@meta.com)>
> > 
> > Escape '**' in the MAINTAINERS descriptions section to prevent
> > reStructuredText from interpreting it as bold/strong inline markup,
> > which causes a warning when running 'make htmldocs'.
[]
> It's nice to eliminate one warning from 'make htmldocs', so this is good
> in that regard. However, there are still multiple problems (not Warnings)
> with '*' characters in the MAINTAINERS file:
> 
> 1) 	   F:	*/net/*		all files in "any top level directory"/net
> 
> In the html output, it shows "/net/" italicized (that's what one * does).
> 
> 2)	   F:	fs/**/*foo*.c	all *foo*.c files in any subdirectory of fs
> 
> In the html output, it shows
> 
> 	F: fs/**/foo.c all foo.c files in any subdirectory of fs
> 
> with both occurrences of "foo.c" italicized (dropping the '*' characters).
> 
> These 2 examples are actively wrong.
> 
> [adding new:]
> We would be better served by just putting file patterns inside ``fs/**/*foo*.c``
> quotation marks IMO.
> 
> Ah, similar to what you do in the table output.
> 
> Oh, with one little glitch:
> E.g., in the very first entry for 3C59X NETWORK DRIVER,
>   F:	Documentation/networking/device_drivers/ethernet/3com/vortex.rst
>   F:	drivers/net/ethernet/3com/3c59x.c
> it looks like automarkup is applied to the Documentation file so these
> 2 files are displayed as:
> 
> networking/device_drivers/ethernet/3com/vortex, drivers/net/ethernet/3com/3c59x.c
> 
> with the Doc file underlined and missing both Documentation and .rst.
> Or maybe that's what you intended since the automarkup link does work.
> It's just not what I expected. Oh well.

Please stop trying to format MAINTAINERS into rst.
It shouldn't be formatted.
It's simple text.

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Mauro Carvalho Chehab]

On Tue, 5 May 2026 02:20:45 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Tue, May 5, 2026 at 2:08 AM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Also, with time, maintainers may change their employers while still
> > keeping their maintainership status.
> >
> > So, I'd say that whatever is there at the "P" entry, or where it is
> > located (either on a ReST file at the Kernel or on some external URL),
> > it should reflect the model that a maintainer or subsystem community
> > that actively participate at the Kernel development agrees with.
> > This should be vendor-agnostic.  
> 
> I am not sure what you mean. By "vendored" I don't mean
> companies/employers, I mean that the file comes from an upstream
> repository:
> 
>   https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md
> 
> Nevertheless, it is true that this really is a special case, in that
> the upstream project decided to provide something that could then be
> fit into the `P:` field.
> 
> One could say "let's ask them to do rst upstream", but to be honest,
> it is simpler to just put a hyperlink to GitHub's rendered file.
> Markdown is anyway a better fit for their file.

Ok. Then it P entry could be:

	P: https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md

> > Generating on the fly is a bad idea, as when one uses:
> >
> >         make O=SOME_DIR
> >
> > It is expected that the original source directory will remain
> > untouched.  
> 
> I am not sure why that would be a problem -- the output would be in
> `objtree`, not in `srctree`, as usual.

No, this won't work. See sphinx-build help:

	$ sphinx-build --help
	usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
	...

	positional arguments:
	  SOURCE_DIR            path to documentation source files
	  OUTPUT_DIR            path to output directory
	  filenames             (optional) a list of specific files to rebuild. Ignored if --write-all is specified


The way Sphinx works is that it will consider a source file
only for stuff inside the SOURCE_DIR positional parameter passed to
sphinx-build. It handles SOURCE_DIR the same way chroot does:
assuming that you add at toctable inside Documentation/index.rst
(e.g on its root level) something like like this:

	/DIR/file.rst
	../DIR/file.rst
	../../../../../../../../../DIR/file.rst

They all will be interpreted as:
	{SOURCE_DIR}/DIR/file.rst

Making impossible to reference any file at the OUTPUT_DIR, except
if you place OUTPUT_DIR inside SOURCE_DIR. 

On normal builds, where we have "output" dir inside "Documentation",
this works, but when O=DIR is used, the output directory is 
typically elsewhere, which effectively breaks O=DIR support.

Besides it, Sphinx makes a 1:1 map between a source rst file
and a destination html file (for make htmldocs).

MAINTAINERS is actually a good example of such limitation: I would
love to produce per-subsystem output files from a single
maintainers.rst file, but Sphinx doesn't allow that.

> 
> > I suggested pandoc as a one-time conversion if one wants to migrate
> > from MD to rst, as for simple documents like this one, it works
> > fine.  
> 
> They are the maintainers, so it is up to them, but it is simpler to
> use a hyperlink.
>
> (The file is trivial, i.e. the conversion can be done in a moment
> without `pandoc`).

Ok.

Thanks,
Mauro

Re: [PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions

[Mauro Carvalho Chehab]

On Mon, 04 May 2026 20:19:50 -0700
Joe Perches <joe@perches.com> wrote:

> On Mon, 2026-05-04 at 14:20 -0700, Randy Dunlap wrote:
> > On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> > From: Matteo Croce <[teknoraver@meta.com](mailto:teknoraver@meta.com)>  
> > > 
> > > Escape '**' in the MAINTAINERS descriptions section to prevent
> > > reStructuredText from interpreting it as bold/strong inline markup,
> > > which causes a warning when running 'make htmldocs'.  
> []
> > It's nice to eliminate one warning from 'make htmldocs', so this is good
> > in that regard. However, there are still multiple problems (not Warnings)
> > with '*' characters in the MAINTAINERS file:
> > 
> > 1) 	   F:	*/net/*		all files in "any top level directory"/net
> > 
> > In the html output, it shows "/net/" italicized (that's what one * does).
> > 
> > 2)	   F:	fs/**/*foo*.c	all *foo*.c files in any subdirectory of fs
> > 
> > In the html output, it shows
> > 
> > 	F: fs/**/foo.c all foo.c files in any subdirectory of fs
> > 
> > with both occurrences of "foo.c" italicized (dropping the '*' characters).
> > 
> > These 2 examples are actively wrong.
> > 
> > [adding new:]
> > We would be better served by just putting file patterns inside ``fs/**/*foo*.c``
> > quotation marks IMO.

The logic actually does that already:

        #
        # 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 = '``%s``' % (details)

The only reason why this patch is needed is for the header part, which
describes that "**" is allowed. If you look at the final code, this
replace code will be only at the header parsing logic:

    def parse_descriptions(self, line):
        """Handle contents of the descriptions section."""

    ...
        # Escape the escapes in preformatted text.
        line = self.linkify(line).replace("\\", "\\\\").replace("**", "\\**")
        self.header += "| " + line

> > 
> > Ah, similar to what you do in the table output.
> > 
> > Oh, with one little glitch:
> > E.g., in the very first entry for 3C59X NETWORK DRIVER,
> >   F:	Documentation/networking/device_drivers/ethernet/3com/vortex.rst
> >   F:	drivers/net/ethernet/3com/3c59x.c
> > it looks like automarkup is applied to the Documentation file so these
> > 2 files are displayed as:
> > 
> > networking/device_drivers/ethernet/3com/vortex, drivers/net/ethernet/3com/3c59x.c
> > 
> > with the Doc file underlined and missing both Documentation and .rst.
> > Or maybe that's what you intended since the automarkup link does work.
> > It's just not what I expected. Oh well.  
> 
> Please stop trying to format MAINTAINERS into rst.
> It shouldn't be formatted.
> It's simple text.

MAINTAINERS is not a simple text. It is a machine-readable text
database.

Thanks,
Mauro

Re: [PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions

[Mauro Carvalho Chehab]

On Tue, 5 May 2026 07:57:25 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> On Mon, 04 May 2026 20:19:50 -0700
> Joe Perches <joe@perches.com> wrote:
> 
> > On Mon, 2026-05-04 at 14:20 -0700, Randy Dunlap wrote:
> > > On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> > > From: Matteo Croce <[teknoraver@meta.com](mailto:teknoraver@meta.com)>  
> > > > 
> > > > Escape '**' in the MAINTAINERS descriptions section to prevent
> > > > reStructuredText from interpreting it as bold/strong inline markup,
> > > > which causes a warning when running 'make htmldocs'.  
> > []
> > > It's nice to eliminate one warning from 'make htmldocs', so this is good
> > > in that regard. However, there are still multiple problems (not Warnings)
> > > with '*' characters in the MAINTAINERS file:
> > > 
> > > 1) 	   F:	*/net/*		all files in "any top level directory"/net
> > > 
> > > In the html output, it shows "/net/" italicized (that's what one * does).
> > > 
> > > 2)	   F:	fs/**/*foo*.c	all *foo*.c files in any subdirectory of fs
> > > 
> > > In the html output, it shows
> > > 
> > > 	F: fs/**/foo.c all foo.c files in any subdirectory of fs
> > > 
> > > with both occurrences of "foo.c" italicized (dropping the '*' characters).
> > > 
> > > These 2 examples are actively wrong.

Heh, I read this too quickly: you're talking about the header descriptions
where we have:

    F: *Files* and directories wildcard patterns.
       A trailing slash includes all files and subdirectory files.
       F:   drivers/net/    all files in and below drivers/net
       F:   drivers/net/*   all files in drivers/net, but not below
       F:   */net/*     all files in "any top level directory"/net
       F:   fs/**/*foo*.c   all *foo*.c files in any subdirectory of fs

Yeah, you're right: the header parsing logic won't handle this well.
This should do the trick:

    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 = False
            self.header += "\n" + line
            return

        # Look for and record field letter to field name mappings:
        #   R: Designated *reviewer*: FullName <address@domain>
        m = re.match(r"\s+(\S):\s+(\S+)", line)
        if m:
            field = m.group(1)
            details = m.group(2)

            if field not in self.fields:
                m = re.search(r"\*([^\*]+)\*", line)
                if m:
                    self.fields[field] = m.group(1)
            elif field in ['F', 'N', 'X', 'K']:
                line = line.replace(details, f'``{details}``')

        # Escape the escapes in preformatted text.
        self.header += "| " + self.linkify(line).replace("\\", "\\\\")

I'll address it in v2.

Thanks,

Thanks,
Mauro

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Gary Guo]

On Tue May 5, 2026 at 6:45 AM BST, Mauro Carvalho Chehab wrote:
> On Tue, 5 May 2026 02:20:45 +0200
> Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
>
>> On Tue, May 5, 2026 at 2:08 AM Mauro Carvalho Chehab
>> <mchehab+huawei@kernel.org> wrote:
>> >
>> > Also, with time, maintainers may change their employers while still
>> > keeping their maintainership status.
>> >
>> > So, I'd say that whatever is there at the "P" entry, or where it is
>> > located (either on a ReST file at the Kernel or on some external URL),
>> > it should reflect the model that a maintainer or subsystem community
>> > that actively participate at the Kernel development agrees with.
>> > This should be vendor-agnostic.  
>> 
>> I am not sure what you mean. By "vendored" I don't mean
>> companies/employers, I mean that the file comes from an upstream
>> repository:
>> 
>>   https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md
>> 
>> Nevertheless, it is true that this really is a special case, in that
>> the upstream project decided to provide something that could then be
>> fit into the `P:` field.
>> 
>> One could say "let's ask them to do rst upstream", but to be honest,
>> it is simpler to just put a hyperlink to GitHub's rendered file.
>> Markdown is anyway a better fit for their file.
>
> Ok. Then it P entry could be:
>
> 	P: https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md

If you send a patch I can queue it up for 7.2. Or would you want this to be
taken via docs tree instead?

Best,
Gary

Re: [PATCH 0/9] Improve process/maintainers output

[Mauro Carvalho Chehab]

On Mon, 4 May 2026 14:13:01 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> > Hi Jon,
> > 
> > As promised, this series improve the output at process/maintainers:
> > instead of a pure enriched text, the maintainer's file content is
> > now converted with a table, and has gained a javascript to allow
> > filtering entries.
> > 
> > The initial patches change the logic to split parsing from
> > output generation. Now, everything is stored into a dict at
> > the parsing phase. This way, it is easier to adjust the
> > directive handler for it to produce a more structured document.
> > 
> > Right now, the entries are sorted alphabetically, per subsystem's
> > name.  
> 
> How is subsystem determined? Just by the heading?
> The MAINTAINERS file doesn't stay sorted so the output isn't sorted
> unless I am just missing something basic.
> 
> See e.g.:
> DRM TTM SUBSYSTEM
> GPU BUDDY ALLOCATOR
> DRM AUTOMATED TESTING

It was preserving the same order as found at MAINTAINERS file, 
where the order is wrong. I added a sort function there (I guess I
had it before internally on my branches some rebases).

-- 
Thanks,
Mauro

Re: [PATCH 9/9] docs: maintainers: add a filtering javascript

[Mauro Carvalho Chehab]

On Mon, 4 May 2026 14:12:50 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> > 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 <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/sphinx/maintainers_include.py | 77 +++++++++++++++++++--
> >  1 file changed, 71 insertions(+), 6 deletions(-)
> > 
> > diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
> > index bbdadf2aa4f3..f85298627da2 100755
> > --- a/Documentation/sphinx/maintainers_include.py
> > +++ b/Documentation/sphinx/maintainers_include.py  
> 
> > +  function addInput() {
> > +    const table = document.getElementById("maintainers-table");
> > +    if (!table) return;
> > +    let input = document.getElementById("filter-table");
> > +    if (!input) {
> > +      const filt_div = document.createElement('div');
> > +      filt_div.innerHTML = `
> > +        <p>Filter:
> > +          <input type="search" id="filter-table" placeholder="subsystem or property (case-sensitive)" />  
> 
> The "placeholder" string does not fit inside the prompt/entry block so it is
> truncated with no way to tell what the missing part is AFAICT.
> Maybe include that after "Filter:"? E.g.,
> 
>            <p>Filter: (subsystem or property, case-sensitive)
> 
> > +        </p>
> > +      `;  

Makes sense. Changed the logic to:

      filt_div.innerHTML = `
        <p>Filter:
          <input type="search" id="filter-table" placeholder="search string"/>
          subsystem or property (case-sensitive)
        </p>
      `;

-- 
Thanks,
Mauro

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Mauro Carvalho Chehab]

On Tue, 05 May 2026 12:16:03 +0100
"Gary Guo" <gary@garyguo.net> wrote:

> On Tue May 5, 2026 at 6:45 AM BST, Mauro Carvalho Chehab wrote:
> > On Tue, 5 May 2026 02:20:45 +0200
> > Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
> >  
> >> On Tue, May 5, 2026 at 2:08 AM Mauro Carvalho Chehab
> >> <mchehab+huawei@kernel.org> wrote:  
> >> >
> >> > Also, with time, maintainers may change their employers while still
> >> > keeping their maintainership status.
> >> >
> >> > So, I'd say that whatever is there at the "P" entry, or where it is
> >> > located (either on a ReST file at the Kernel or on some external URL),
> >> > it should reflect the model that a maintainer or subsystem community
> >> > that actively participate at the Kernel development agrees with.
> >> > This should be vendor-agnostic.    
> >> 
> >> I am not sure what you mean. By "vendored" I don't mean
> >> companies/employers, I mean that the file comes from an upstream
> >> repository:
> >> 
> >>   https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md
> >> 
> >> Nevertheless, it is true that this really is a special case, in that
> >> the upstream project decided to provide something that could then be
> >> fit into the `P:` field.
> >> 
> >> One could say "let's ask them to do rst upstream", but to be honest,
> >> it is simpler to just put a hyperlink to GitHub's rendered file.
> >> Markdown is anyway a better fit for their file.  
> >
> > Ok. Then it P entry could be:
> >
> > 	P: https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md  
> 
> If you send a patch I can queue it up for 7.2. Or would you want this to be
> taken via docs tree instead?

It doesn't matter much but placing it at the documentation series
will keep this change together with the other patches, so I guess
it would be a little better.

I'll be sending the new patch series soon with this change there
as well.

-- 
Thanks,
Mauro

Re: [PATCH 8/9] docs: maintainers_include: don't ignore invalid profile entries

[Miguel Ojeda]

On Tue, May 5, 2026 at 7:45 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> No, this won't work. See sphinx-build help:

That doesn't sound like a fundamental issue, i.e. we could work around
it. Anyway, it is not something we desperately need :)

Thanks!

Cheers,
Miguel