[PATCH v2 00/11] Auto-generate maintainer profile entries

[Mauro Carvalho Chehab]

On Sat, 18 Apr 2026 17:05:56 -0700
Randy Dunlap <rdunlap at infradead.org> wrote:

> On 4/16/26 11:11 PM, Mauro Carvalho Chehab wrote:
> > Hi Jon,
> > 
> > This patch series change the way maintainer entry profile links
> > are added to the documentation. Instead of having an entry for
> > each of them at an ReST file, get them from MAINTAINERS content.
> > 
> > That should likely make easier to maintain, as there will be a single
> > point to place all such profiles.
> > 
> > The output is a per-subsystem sorted (*) series of links shown as a
> > list like this:
> > 
> >     - Arm And Arm64 Soc Sub-Architectures (Common Parts)
> >     - Arm/Samsung S3C, S5P And Exynos Arm Architectures
> >     - Arm/Tesla Fsd Soc Support
> >     ...
> >     - Xfs Filesystem
> > 
> > Please notice that the series is doing one logical change per patch.
> > I could have merged some changes altogether, but I opted doing it
> > in small steps to help reviews. If you prefer, feel free to merge
> > maintainers_include changes on merge.
> > 
> > There is one interesting side effect of this series: there is no
> > need to add rst files containing profiles inside a TOC tree: Just
> > creating the file anywhere inside Documentation and adding a P entry
> > is enough. Adding them to a TOC won't hurt.
> > 
> > Reported-by: Randy Dunlap <rdunlap at infradead.org>
> > Suggested-by: Dan Williams <djbw at kernel.org>
> > Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
> > 
> > (*) At the end, I opted to use sorted(), just to ensure it, even
> >     knowing that MAINTAINER entries are supposed to be sorted, as
> >     the cost of sorting ~20 already-sorted entries is negligible.
> > 
> > ---
> > 
> > v2:
> >   - I placed the to MAINTAINERS changes at the beginning.
> >   - fix a bug when O=DOCS is used;
> >   - proper handle glob "P" entries (just in case, no profiles use it ATM);
> >   - when SPHINXDIRS=process, instead of producing warnings, point to
> >     entries at https://docs.kernel.org;
> >   - MAINTAINERS parsing now happens just once;
> >   - The output won't be numered for entries inside numered TOC trees;
> >   - TOC tree is now hidden;
> >   - instead of display a TOC tree, it shows a list of profiles,
> >     ordered and named after file system name taken from MAINTAINERS file;
> >   - At the output list, both https and file profiles are shown the same
> >     way.
> > 
> > Mauro Carvalho Chehab (11):
> >   MAINTAINERS: add an entry for media maintainers profile
> >   MAINTAINERS: add maintainer-tip.rst to X86
> >   docs: maintainers_include: auto-generate maintainer profile TOC
> >   docs: auto-generate maintainer entry profile links
> >   docs: maintainers_include: use a better title for profiles
> >   docs: maintainers_include: add external profile URLs
> >   docs: maintainers_include: preserve names for files under process/
> >   docs: maintainers_include: Only show main entry for profiles
> >   docs: maintainers_include: improve its output
> >   docs: maintainers_include: fix support for O=dir
> >   docs: maintainers_include: parse MAINTAINERS just once
> > 
> >  .../maintainer/maintainer-entry-profile.rst   |  24 +--
> >  .../process/maintainer-handbooks.rst          |  17 +-
> >  Documentation/sphinx/maintainers_include.py   | 161 +++++++++++++++---
> >  MAINTAINERS                                   |   2 +
> >  4 files changed, 150 insertions(+), 54 deletions(-)
> >   
> 
> Just a note, not asking for a change or fix:
> 
> AFAICT, all P: entries are now listed nicely except for:
> 
> P:	rust/pin-init/CONTRIBUTING.md

That's because it doesn't follow what's expected for "P":
either a file that Sphinx can read (rst files), placed inside
Documentation/ and added to Sphinx toctree or an external html URL. 

The way it is, the subsystem profile regex won't get it.

While it is not hard to add an exception, IMO the best would be
to do:

	$ pandoc -fgfm -trst rust/pin-init/CONTRIBUTING.md > Documentation/process/pin-init.rst
	$ sed -i s,rust/pin-init/CONTRIBUTING.md,Documentation/process/pin-init.rst, MAINTAINERS 
	$ git rm rust/pin-init/CONTRIBUTING.md
	$ git add Documentation/process/pin-init.rst
	$ git commit -as

> 
> so for the series:
> Reviewed-by: Randy Dunlap <rdunlap at infradead.org>
> Tested-by: Randy Dunlap <rdunlap at infradead.org>

Thanks!

Mauro