Re: [PATCH 0/8] Auto-generate maintainer profile entries

[Randy Dunlap]

Hi Mauro,

Thanks for tackling this issue.

On 4/15/26 1:52 AM, Mauro Carvalho Chehab wrote:
> Date: Tue, 14 Apr 2026 16:29:03 +0200
> From: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> To: Albert Ou <aou@xxxxxxxxxxxxxxxxx>, Jonathan Corbet <corbet@xxxxxxx>, Dan Williams <djbw@xxxxxxxxxx>, Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>, Palmer Dabbelt <palmer@xxxxxxxxxxx>, Paul Walmsley <pjw@xxxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>, Randy Dunlap <rdunlap@xxxxxxxxxxxxx>, linux-doc@xxxxxxxxxxxxxxx, linux-kernel@xxxxxxxxxxxxxxx, linux-riscv@xxxxxxxxxxxxxxxxxxx, workflows@xxxxxxxxxxxxxxx, Alexandre Ghiti <alex@xxxxxxxx>, Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>
> Message-ID: <cover.1776176108.git.mchehab+huawei@xxxxxxxxxx>
> 
> Hi Dan/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.
> 
> On this version, I added Dan's text to patch 4.
> 
> I also added a couple of other patches to improve its output. While
> I could have them merged at the first patch, I opted to make them
> separate, as, in case of problems or needed changes, it would be
> easier to revert or modify the corresponding logic. Also, it should
> be better to review, in case one wants some changes there.
> 
> The main changes against RFC are:
> 
> - now, the TOC will be presented with 1 depth identation level,
>   meaning that it would look like a list;
> - for files outside Documentation/process, it will use the name of
>   the subsystem with title capitalization for the name of the
>   profile entry;
> - the logic also parses and produces a list of profiles that are
>   maintained elsewhere, picking its http/https link;
> - entries are now better sorted: first by subsystem name, then
>   by its name.
> 
> Suggested-by: Dan Williams <djbw@xxxxxxxxxx>
> Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
> 
> Mauro Carvalho Chehab (8):
>   docs: maintainers_include: auto-generate maintainer profile TOC
>   MAINTAINERS: add an entry for media maintainers profile
>   MAINTAINERS: add maintainer-tip.rst to X86
>   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
> 
>  .../maintainer/maintainer-entry-profile.rst   |  24 +---
>  .../process/maintainer-handbooks.rst          |  17 ++-
>  Documentation/sphinx/maintainers_include.py   | 131 +++++++++++++++---
>  MAINTAINERS                                   |   2 +
>  4 files changed, 128 insertions(+), 46 deletions(-)

When building htmldocs with O=DOCS, I get a bunch of warnings.
I tested against today's linux-next tree.

The 'make O=DOCS htmldocs' warnings are (subset of all warnings):

linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-kvm-x86' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/filesystems/xfs/xfs-maintainer-entry-profile' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-soc-clean-dts' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-netdev' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-tip' [toc.not_readable]

linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]

linux-next/MAINTAINERS:1: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc' [ref.doc]
linux-next/MAINTAINERS:2: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
linux-next/MAINTAINERS:3: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
linux-next/MAINTAINERS:5: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
linux-next/MAINTAINERS:6: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]


-- 
~Randy