Re: Intersphinx ([TECH TOPIC] Kernel documentation)

[Jonathan Corbet <corbet@lwn.net>]

"Theodore Ts'o" <tytso@mit.edu> writes:

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

There will be a lot of broken cross-references; the explicit ones (as
opposed to those created by the automarkup code) will generate warnings. 

> 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.?

Yes, in general, but code changes that affect kerneldoc comments could
also bring about a change.

> 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?

Yes, it would.  But that can be done now with

  make SPHINXDIRS=whatever htmldocs

...with pretty much the same effect.

> 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....

Well, we *could* set up intersphinx to fetch those files from kernel.org
automatically, but I suspect I'm not the only one who would be reluctant
to see the build start reaching out onto the net.  Alternatively, we
could add a script that would have to be run explicitly to do that
fetch.

Thanks,

jon