Skip to contentSkip to conversation

docs: escape ** glob pattern in MAINTAINERS descriptions

PATCH In review Matteo Croce 4 participants 4 messages Apr 9 – Apr 19

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: escape ** glob pattern in MAINTAINERS descriptions

From: Matteo Croce <[email protected]>

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")
---
 Documentation/sphinx/maintainers_include.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/maintainers_include.py +2 -1
index 519ad18685b2..54f34f47c9ee 100755
@@ -89,7 +89,8 @@ class MaintainersInclude(Include):
             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)
Signature · 1 line
2.50.1
reviewer
#1 lore raw

Hi,

Quoted 17 lines · Matteo Croce

From: Matteo Croce <[email protected]>

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")
---
 Documentation/sphinx/maintainers_include.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/maintainers_include.py +0 -0
index 519ad18685b2..54f34f47c9ee 100755

Documentation/sphinx/maintainers_include.py class MaintainersInclude(Include): · line 96

Quoted 9 lines
Documentation/sphinx/maintainers_include.py +2 -1
@@ -89,7 +89,8 @@ class MaintainersInclude(Include):
             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)

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.

I didn't look at any other possible issues.

Signature · 1 line
~Randy
maintainer
#2 lore raw
Quoted 25 lines · Randy Dunlap

Hi,

Quoted 22 lines · Matteo Croce

From: Matteo Croce <[email protected]>

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")
---
 Documentation/sphinx/maintainers_include.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/maintainers_include.py +1 -1
index 519ad18685b2..54f34f47c9ee 100755
@@ -89,7 +89,8 @@ class MaintainersInclude(Include):
             output = None
             if descriptions:
                 # Escape the escapes in preformatted text.
-                output = "| %s" % (line.replace("\\", "\\\\"))
+                output = "| %s" % (line.replace("\\", "\\\\")
Quoted 8 lines

Documentation/sphinx/maintainers_include.py class MaintainersInclude(Include): · line 96

Quoted 4 lines
Documentation/sphinx/maintainers_include.py +1 -0
+                                        .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)

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:

I've mentioned this before but done nothing about it ... I really wonder about the value of bringing in the MAINTAINERS file in the first place. Do we think that anybody is reading it in the rendered docs?

jon

#3 lore raw
Quoted 4 lines · On Fri, 10 Apr 2026 06:50:02 -0600 Jonathan Corbet <[email protected]> wrote:
Quoted 2 lines · Randy Dunlap

Hi,

Quoted 8 lines
Quoted 8 lines · Matteo Croce
Quoted 7 lines

From: Matteo Croce <[email protected]>

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")

It is probably a little too late for that, but do we need "**" pattern?

Quoted 24 lines
Quoted 15 lines
Quoted 15 lines
---
 Documentation/sphinx/maintainers_include.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/maintainers_include.py +1 -1
index 519ad18685b2..54f34f47c9ee 100755
@@ -89,7 +89,8 @@ class MaintainersInclude(Include):
             output = None
             if descriptions:
                 # Escape the escapes in preformatted text.
-                output = "| %s" % (line.replace("\\", "\\\\"))
+                output = "| %s" % (line.replace("\\", "\\\\")
Quoted 8 lines

Documentation/sphinx/maintainers_include.py class MaintainersInclude(Include): · line 96

Quoted 4 lines
Documentation/sphinx/maintainers_include.py +1 -0
+                                        .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)  

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:

Quoted 3 lines

I've mentioned this before but done nothing about it ... I really wonder about the value of bringing in the MAINTAINERS file in the first place. Do we think that anybody is reading it in the rendered docs?

Short answer:

On my view yes.

---

Long answer:

Your question made me re-think if what we're doing is the best way, so I ended deciding doing some experiments during the weekend.

I think we need to keep it there, but IMO we need to add more value to it at the rendered docs. I ended doing some tests here, by first storing maintainers entry into a dict and then playing with its output.

On my tests (python 3.14), creating a directory "foo" and placing there just a small index.rst with a TOC and maintainers.rst and running sphinx-build-wrapper (to avoid performance measurement noise), I got:

- current generation takes ~13 seconds;
- doing a parsing step to create a dict and increasing string size instead of joining lists - time reduced to ~11 seconds, to produce the same content;

I then tested 3 different alternatives:

1. Sorting/grouping entries per ML (excluding LKML and giving preference to kernel.org where multiple lists are present) Time reduced to 9 seconds;

2. doing (1) and using iglob to pick the actual number of files, sorting entries inside groups per their number of files. On my machine with a fast SSD, time increased to ~12 seconds;

3. converting into a table with two columns:
- subsystem name;
- properties (with all fields per subsystem.

time increased to ~9 seconds.

After looking at the results, IMO (3) offered a nice look-and-feel, while providing a good performance compromise.

It was also pretty easy to add 46-lines javascript (incluiding SPDX) to allow filtering the table by any field or subsystem.

I'll likely post later this week a patch series with (3).

Thanks,
Mauro