Re: Intersphinx ([TECH TOPIC] Kernel documentation)

["Theodore Ts'o" <tytso@mit.edu>]

On Thu, Jun 29, 2023 at 03:34:41PM -0600, Jonathan Corbet wrote:
> 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.

Yeah, that's a bit of a bummer.  It sounds a bit like TeX/LaTeX's
various *.aux files that are used to generate the numbers for
foornotes, et.al.  But I'll note that while I would do two passes of
running LaTeX before doing sending out the final version of my paper,
most of the time, I'd only run LaTeX once, and live with the fact that
some section numbers or footnotes would be something like [???]
instead of containing the properreference.

From the perspective of someone who is editing the docs, how
usable/unusable is the sphinx output without these inventory files?  Or
if the inventory files are out of date?  And am I right they only
change when someone adds a new section, or a new anchor point for a
cross reference, etc.?

If the goal is for someone to check and see whether the output of a
particular part of the docs looks OK after doing a quick edit (e.g.,
did I mess up a table), it would seem that doing a single pass of a
single "book" would be faster, right?  And would it be good enough for
them to make sure that their edits to a particular .rst file looked
OK?

I also wonder if there's a way people could download inventory files
from some web site so their first pass run of sphinx would look
prettier?  Assuming that intersphinx can deal with slightly
out-of-sync inventory files, of course....

						- Ted