docs: escape ** glob pattern in MAINTAINERS descriptions
Subsystems (2)
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'.
--- Documentation/sphinx/maintainers_include.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
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)
Signature · 1 line
2.50.1
Randy Dunlap
reviewerHi,
Quoted 17 lines · Matteo Croce
From: Matteo Croce <[email protected]>
Escape '**' in the
MAINTAINERSdescriptions 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 <[email protected]>--- Documentation/sphinx/maintainers_include.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/sphinx/maintainers_include.py +0
-0
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
Jonathan Corbet
maintainerQuoted 25 lines · Randy Dunlap
Hi,
Quoted 22 lines · Matteo Croce
From: Matteo Croce <[email protected]>
Escape '**' in the
MAINTAINERSdescriptions 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 <[email protected]>--- Documentation/sphinx/maintainers_include.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/sphinx/maintainers_include.py +1
-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("\\", "\\\\")
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
MAINTAINERSfile:
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
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
MAINTAINERSdescriptions 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
Signed-off-by Matteo Croce <[email protected]>--- Documentation/sphinx/maintainers_include.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/sphinx/maintainers_include.py +1
-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("\\", "\\\\")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
MAINTAINERSfile:
Quoted 3 lines
I've mentioned this before but done nothing about it ... I really wonder about the value of bringing in the
MAINTAINERSfile 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