Em Thu, 11 Sep 2025 13:47:54 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > 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... There are a couple of different usecase scenarios for building docs. 1) The first and most important one is to produce book(s) for people to use. This is usually done by some automation, and the result is placed on places like: - https://docs.kernel.org/ and on subsystem-specific places like: - https://linuxtv.org/downloads/v4l-dvb-apis-new/ for scenario (1), taking twice the time to build is not an issue, as nobody will be sitting on a chair waiting for the build to finish. On such scenario, SPHINXDIRS is important on subsystem-specific docs. For instance, on media, we use SPHINXDIRS to pick parts of 3 different books: - Documentation/admin-guide/media/ - Documentation/driver-api/media/ - Documentation/userspace-api/media/ What media automation does, once per day, is: # Non-essencial parts of index.rst dropped cat <<END >Documentation/media/index.rst ================================ Linux Kernel Media Documentation ================================ .. toctree:: admin-guide/index driver-api/index userspace-api/index END rsync -uAXEHlaSx -W --inplace --delete Documentation/admin-guide/media/ Documentation/media/admin-guide rsync -uAXEHlaSx -W --inplace --delete Documentation/driver-api/media/ Documentation/media/driver-api rsync -uAXEHlaSx -W --inplace --delete Documentation/userspace-api/media/ Documentation/media/userspace-api make SPHINXDIRS='media' CSS='$CSS' DOCS_THEME='$DOCS_THEME' htmldocs make SPHINXDIRS='media' pdfdocs make SPHINXDIRS='media' epubdocs 2) CI tests. Here, taking more time usually is not a problem, except when CI is used before pushing stuff, and the developer has to wait it to finish before pushing. For scenario (2), a build time increase is problematic, as, if it now takes twice the time, a change like that will require twice the resources for the build with may increase costs. 3) developers who touched docs. They want a way to quickly build and verify the output for their changes. Here, any time increase is problematic, and SPHINXDIRS play an important hole by allowing them to build only the touched documents. For instance, when I was developing Netlink yaml plugin, I had to use dozens of times: make SPINXDRS=Documentation/netlink/specs/ htmldocs If I had to build the entire documentation every time, the development time would increase from days to weeks. Looking on those three scenarios, the only one where intersphinx is useful is (1).
