Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> writes: > On Thu, 11 Sep 2025, Jonathan Corbet <corbet@xxxxxxx> wrote: >> 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. Well, I think that the number of existing directories needs to be reduced rather further. I made progress in that direction by coalescing all the arch docs under Documentation/arch/. I would like to do something similar with all the device-specific docs, creating Documentation/devices/. Then we start to get to a reasonable number of books. > 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. That's a good point, I hadn't looked into that part. The builder phase takes a lot of the time, if that could be cut out things would go faster. > 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. That is true. My point though is that, to get the references right with a *full* build, a two-pass approach is needed though, as you suggest, perhaps the first pass could be faster. Thanks, jon
