Feature request: Create new inventory builder

[jdillard]

Is your feature request related to a problem? Please describe.

Sometimes it is useful to build a group of Sphinx projects together in a single CI/CD job, for example the package documentation for a collection of internal Python packages or maybe a collection of auto-generated content.

The issue comes when building the projects in series while attempting to use interpsphinx between the projects and one project can't find the object.inv for a yet to be built project in that group. To solve this scenario, it seems having a new inventory builder would be useful so that the CI/CD build could happen in two stages, 1) use the inventory builder to build all the projects' object.inv files, then 2) loop back and run all the full builds so all the cross-references are in place. This new builder potentially has other uses beyond this use case.

Describe the solution you'd like

In researching this I can across a related issue, #7891. And in that issue it looks like they implemented an inventory_builder.py, so inspiration for a new inventory builder that only builds the objects.inv file already exists.

Describe alternatives you've considered

Alternatively, Sphinx could not support cross-referencing within grouped builds, but that seems unnecessarily restrictive. I've also implemented workarounds for checking deployed assets as a backup, but that is not a proper representation of the local references and temporarily fails until a deploy is forced when cross-references are changed.

Additional context

I was going to attempt a local implementation using an extension, but figured it was worth starting a discussion in parallel, as it would be nice as a core feature.

[mgeier]

I think an inventory builder would be a good idea.

I would have had a different use case: I wanted to include two separate Sphinx projects in a top-level LaTeX file (according to this example: https://github.com/spatialaudio/nbsphinx/tree/master/include-in-latex).
One of the Sphinx projects references the other one, and I wanted to create intra-document cross-references for that (instead of creating links to the online HTML version, which would have happened by default).

I did this by creating an objects.inv file when building the LaTeX version of one of the projects (https://github.com/mgeier/diss/blob/5bf94876a0b2ec6c10eb792d49c31452999995af/sphinx-splines/conf.py#L27-L37) and manually loading that objects.inv file when building the other one (https://github.com/mgeier/diss/blob/5bf94876a0b2ec6c10eb792d49c31452999995af/sphinx-asdf/conf.py#L22-L55).

This did work because the links only went from one project to the other, and not in the other direction.
In case of bi-directional links this would have been more complicated, but I think an inventory builder might have helped.

[chrisjsewell]

I think this makes sense 👍 ,

I have an orthogonal use case, not to output the objects.inv itself, but to output a "human-readable" format, to allow users to view all the reference targets in their projects (and where they are located), which could also be utilised by Language Servers.

In this respect, it is somewhat of a shame, that get_objects does not offer the possibility to retrieve the line number for the objects, which would be awesome for "jump to target" features:

sphinx/sphinx/domains/__init__.py

Line 358 in 5523c9b

def get_objects(self) -> Iterable[tuple[str, str, str, str, str, int]]:

[picnixz]

but to output a "human-readable" format, to allow users to view all the referenc

Technically, using python -m sphinx.ext.intersphinx objects.inv (or any remote URL to that file) gives you a somewhat human readable thing but I agree that we could have perhaps a prettier format.

For the line number, it's a bit hard because not all objects have "line number" (it depends where the reference is created and whether we should consider line continuations or not)