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

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

[Matteo Croce]

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>
---
 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 519ad18685b2..54f34f47c9ee 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -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)
-- 
2.50.1

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

[Randy Dunlap]

Hi,

On 4/9/26 3:31 PM, Matteo Croce 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>
> ---
>  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 519ad18685b2..54f34f47c9ee 100755
> --- a/Documentation/sphinx/maintainers_include.py
> +++ b/Documentation/sphinx/maintainers_include.py
> @@ -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.

-- 
~Randy

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

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> Hi,
>
> On 4/9/26 3:31 PM, Matteo Croce 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>
>> ---
>>  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 519ad18685b2..54f34f47c9ee 100755
>> --- a/Documentation/sphinx/maintainers_include.py
>> +++ b/Documentation/sphinx/maintainers_include.py
>> @@ -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:

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

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

[Mauro Carvalho Chehab]

On Fri, 10 Apr 2026 06:50:02 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> Randy Dunlap <rdunlap@infradead.org> writes:
> 
> > Hi,
> >
> > On 4/9/26 3:31 PM, Matteo Croce 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")

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


> >> Signed-off-by: Matteo Croce <teknoraver@meta.com>
> >> ---
> >>  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 519ad18685b2..54f34f47c9ee 100755
> >> --- a/Documentation/sphinx/maintainers_include.py
> >> +++ b/Documentation/sphinx/maintainers_include.py
> >> @@ -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:  
> 
> 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