Expose build option for only building intersphinx object inventory.

[ghost]

Subject: sphinx-build needs to expose a build option which only builds the intersphinx object inventory for the specified project.

Problem

Given two projects: {A, B} Given both projects are using the intersphinx extension Given that both projects are built using the same build system

You cannot add an anchor like ".. _B-anchor:" to B and a link like ":ref:B <B:B-anchor>" to A in the same commit.

Project A cannot reference the anchor in B until the new build of B has been deployed. Project A will also fail to build until B has been deployed. This can be circumvented by overwriting the URLs in the intersphinx mapping with absolute file paths at build time, but this is messy.

Further, without a complex dependency graph for builds, adding anchors and links to both A and B simultaneously is impossible to successfully build without ignoring errors, as the objects inventory for A and B cannot be built without validating that all links in A and B are valid.

It would be great if the intersphinx-extension objects-inventory could be built without checking the link validity of the project, to allow build systems which build many projects to accommodate these types of wiring commits without having to maintain a complex dependency graph of projects or splitting very related changes across multiple commits.

[tk0miya]

To build inventory data is almost same as building HTML in processing of Sphinx. So I feel I wonder is there any worth to make the option. How about build the your document as HTML once to build the inventories even if there are errors?

[nadiasvertex]

I personally have a use for this: I build several documentation packages at once, one after the other, and then copy them to our documentation server. They reference each other. It would be great to be able to generate the inventory on a pre-pass for all of them first. For now I generate HTML twice in order to get the inventory files.

[tk0miya]

As a workaround, you can do it with a simple extension. I believe it might work fine.

from sphinx.builders.html import StandaloneHTMLBuilder


class InventoryBuilder(StandaloneHTMLBuilder):
    name = 'inventory'

    def write_doc(self, docname, doctree):
        pass

    def finish(self):
        self.dump_inventory()


def setup(app):
    app.add_builder(InventoryBuilder)

I don't know this is merged into sphinx-core or not. Personally, I feel this is not important for me.

[arwedus]

I'd also be very interested in this to make a clean two stage build if two projects reference each other.

[MathiasMagnus]

@tk0miya Just putting it out there: I also came across the same issue. I'm working on https://rocm.docs.amd.com which is build from some ~54 repos linking to each other using intersphinx. A current initiative is to let ecosystem component developers and the documentation team build get an offline of the entire documentation for tighter development loops. Generating all the HTMLs for so many projects is a non-negligible overhead only to then to kick off a second build in which links aren't broken.

A straightforward way of doing this would allow for far less gymnastics.

[arwedus]

@MathiasMagnus : We also use intersphinx (and sphinx needs external-needs) for a multi-project sphinx build heavily. We found out a way how to do this, and created a small extension that adds an "inventories" Builder that skips the write phase. It's essentially just that. If I find time I'll add a re-write of the idea (our open source policy is complicated) to my personal space.