Re: [PATCH v2 04/11] docs: maintainers_include: clean most SPHINXDIRS=process warnings

[Mauro Carvalho Chehab]

On Tue, 5 May 2026 12:53:01 -0700
Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:

> On 5/5/26 6:25 AM, Mauro Carvalho Chehab wrote:
> > building docs with SPHINXDIRS=process is too noisy, as it
> > generates lots of undefined refs. Fixing it is easy: just let
> > linkify generate html URLs for the broken links when SPHINXDIRS
> > is used.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>  
> 
> Is this specific to SPHINXDIRS=process?
> I don't see anything here checking for "process".
> 
> If this is process-specific, why?
> Or is it just for SPHINXDIRS="<subdir(s)>"?

It is specific with using SPHINXDIRS=<subdir> where <subdir>
contains one of the two meta-tags defined by the extension.
Yet, right now, just "process" subdir has them:

	$ git grep "\.\. maint" Documentation
	Documentation/process/maintainer-handbooks.rst:.. maintainers-profile-toc::
	Documentation/process/maintainers.rst:.. maintainers-include::

See, what this patch does in practice is to avoid a massive flood of
warnings if one uses:

	$ make SPHINXDIRS=process htmldocs

As ".. maintainers-include::" would create lots of ":doc:" references
to documents outside "process" subdir. With this patch, they're
converted into https links to docs.kernel.org, thus cleaning up the
warnings, while creating an output that will contain working cross
references.

Thanks,
Mauro