Re: Intersphinx ([TECH TOPIC] Kernel documentation)

[Jonathan Corbet <corbet@lwn.net>]

Jani Nikula <jani.nikula@intel.com> writes:

> - Consider splitting the whole documentation to multiple smaller
>   projects, and linking between them using intersphinx. (This may be a
>   tall order.)

So for anybody who is interested, I went and revisited this.  Actually
splitting the docs into separate books would not be that hard, and
intersphinx will indeed manage the cross-references between them without
a lot of extra effort on our part.

There is a catch, though: In order to be able to create the cross
references, intersphinx has to be able to read the "objects.inv" file
for every other document it refers to.  That file, of course, is created
by building the docs.  In practice this means that, to generate a
complete set of manuals from a clean repository, it would be necessary
to do *two* complete builds - one to create the inventory files, and one
to use them.

That is not exactly the path to a faster build experience.

My conclusion is that intersphinx is aimed at enabling easy linking
between entirely independent sets of manuals, where you can't build
everything together in any case, and not really at our use case.  I'm
not convinced it buys us much over "make SPHINXDIRS=".

jon