0005. Remote documents are three kinds, not one

Status

Accepted.

Context

A documentation set almost always references material it does not build: an upstream project’s manual, a vendor’s API reference, a corporate document living behind another URL entirely.

An upstream Sphinx site publishes objects.inv; an upstream Doxygen site publishes a tag file. Both are exactly what the engine already consumes between two locally built documents. Treating a remote peer as an opaque URL throws away cross-referencing that costs almost nothing to keep.

Sphinx and Doxygen are not symmetric here, which is what shaped the decision. Sphinx’s own intersphinx extension fetches a remote objects.inv over HTTP itself — mature, cached, retrying, entirely Sphinx’s machinery. Doxygen has no equivalent capability at all: a tag file must be a local file.

Decision

Three kinds, whitelisted and independently validated:

external

No index, no cross-referencing. A named link under the set’s external base URL, reachable through the :qmsdoc: role.

sphinx-external

A remote Sphinx site. The engine adds it to intersphinx_mapping; Sphinx fetches objects.inv itself at build time. Requires remote-url:.

doxygen-external

A remote Doxygen site. The engine downloads the tag file, at build time, in the same stage local tag files are produced, and wires it into doxylink and TAGFILES with the remote site as its location base. Requires remote-url: and remote-tagfile: — two separate, separately validated fields, because Doxygen tag-file names are not standardised the way objects.inv is and one cannot be derived from the other.

Consequences

• A remote peer is fetched fresh on every build, with no caching. That matches how the engine already recomputes tag files and navigation links, and it makes a stale local copy impossible.

• Because the download is wired into the same stage-1 gate every local document already depends on, no per-consumer wiring is needed: existing documents pick up the dependency for free.