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

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

Em Thu, 11 Sep 2025 07:38:56 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > On Thu, Sep 11, 2025 at 01:23:55PM +0300, Jani Nikula wrote:  
> >> > 1. SPHINXDIRS. It needs a lot of magic to work, both before running
> >> >    sphinx-build and after (inside conf.py);  
> >> 
> >> Makes you wonder if that's the right solution to the original
> >> problem. It was added as a kind of hack, and it stuck.  
> >
> > The problem is, IMHO, due to the lack of flexibility of sphinx-build:
> > It should have a way on it to do partial documentation builds.  
> 
> A couple of times I have looked into using intersphinx, making each book
> into an actually separate book.  The thing I always run into is that
> doing a complete docs build, with working references, would require
> building everything twice.  This is probably worth another attempt one
> of these years...

The big advantage of intersphinx is for PDF and LaTeX output, as
this is the only way to have cross-references there.

It is also good for subsystem-specific books (or "sub-"books) like:

	- Documentation/admin-guide/media/
	- Documentation/driver-api/media/
	- Documentation/userspace-api/media/

Right now, we create a single book with all those tree, but I would
prefer to build each of them as separate units, as they are for separated
audiences, but only if cross-references will be solved in a way that
html and pdf docs will point to the other books stored at linuxtv.org.

For html, this won't be any different, in practice, from what we have,
but for PDF and ePub, this would mean smaller books.

Thanks,
Mauro