On Thu, 11 Sep 2025, Jonathan Corbet <corbet@xxxxxxx> wrote: > Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
