[PATCH 0/9] Improve process/maintainers output

Mauro Carvalho Chehab
2026-05-04T15:51:28Z

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