Re: [PATCH v4 08/19] tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Fri, 12 Sep 2025 13:34:17 +0200
Vegard Nossum <vegard.nossum@oracle.com> escreveu:

> On 12/09/2025 12:16, Jani Nikula wrote:
> >> Here, any time increase is problematic, and SPHINXDIRS play an important
> >> hole by allowing them to build only the touched documents.  
> > This is actually problematic, because the SPHINXDIRS partial builds will
> > give you warnings for unresolved references that are just fine if the
> > entire documentation gets built.  
> 
> I admit I don't have a full overview of all the problems that are being
> solved here (in existing and proposed code), but how hard would it be to
> convert the whole SPHINXDIRS thing into a Sphinx plugin that runs early
> and discards documents outside of what the user wants to build? By
> "discards" I mean in some useful way that reduces runtime compared to a
> full build while retaining some benefits of a full build (reference
> checking)?

That's not a bad idea, but I guess it is not too easy to implement - at
least inside a Sphinx plugin.

The good news is that conf.py has already a logic to ignore patterns that
could be tweaked and/or placed on a plugin.

The bad news is that existing index.rst files will now reference
non-existing docs. No idea how to "process" them to filter out
such docs. It is probably doable. See, SPHINXDIRS supports pinpointing
any directory, not just Documentation child directories. So, eventually,
such plugin would also need to "fake" the main index.rst. Now, the
question is, if we pick for instance:

	SPHINXDIRS="netlink/spec networking"

What would be the main title that would be at the main index.rst?
I suspect that, for such cases, the title of the index would need
to be manually set at the command line interface.

Another aspect is that SPHINXDIRS affect latex document lists, 
which can be problematic.


Thanks,
Mauro