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

[Jani Nikula <jani.nikula@linux.intel.com>]

On Thu, 11 Sep 2025, Jonathan Corbet <corbet@lwn.net> wrote:
> 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...

I think the main factor in that should be whether it makes sense from
overall documentation standpoint, not the technical details.

Having several books might make sense. It might even be helpful in
organizing the documentation by audiences. But having the granularity of
SPHINXDIRS with that would be overkill. And there needs to be a book to
bring them together, and link to the other books, acting as the landing
page.

I believe it should be possible to generate the intersphinx inventory
without generating the full html or pdf documentation. So I don't think
it's actually two complete docs builds. It might speed things up to have
a number of independent documentation builds.

As to the working references, IIUC partial builds with SPHINXDIRS
doesn't get that part right if there are references outside of the
designated dirs, leading to warnings.


BR,
Jani.






-- 
Jani Nikula, Intel