Intersphinx

The [intersphinx] section configures cross-project references against external Sphinx inventories (objects.inv files), mirroring Sphinx’s intersphinx extension. Each configured project makes its documented objects (labels, terms, functions, and so on) resolvable from your own project.

Minimal example

[intersphinx]
cache_days = 5                    # 0 = always refresh, negative = never expire
timeout = 30.0                    # seconds per HTTP request
disabled_reftypes = ["std:doc"]   # "*" and "domain:*" forms supported
offline = false                   # never fetch; serve cache or fail soft

[intersphinx.projects.python]
url = "https://docs.python.org/3"
# optional; defaults to ["<url>/objects.inv"]; entries are URLs or paths
# relative to the ubproject.toml directory; tried in order (Sphinx parity)
inventories = ["https://docs.python.org/3/objects.inv"]

[intersphinx.projects.sphinx]
url = "https://www.sphinx-doc.org/en/master"

Options

cache_days

Type: integer (default: 5)

Inventory cache lifetime in days, matching Sphinx’s intersphinx_cache_limit semantics: a positive value expires a cached inventory after that many days (after which it is revalidated with a conditional request), 0 always refreshes, and a negative value never expires the cache.

timeout

Type: number (default: 30.0)

Timeout, in seconds, for each inventory HTTP request.

disabled_reftypes

Type: array of strings (default: ["std:doc"])

Reference types excluded from the automatic (un-qualified) fallback, such as "std:doc". The "*" (all) and "domain:*" (whole-domain) wildcard forms are supported. Explicit inventory-qualified lookups ignore this list.

Note

Automatic external resolution of plain :doc: references is not currently implemented (independent of this list) — use the explicit :external:doc:`…` role form to link an external document.

offline

Type: boolean (default: false)

When true, never perform network fetches: inventories are served from the cache (stale is acceptable) or the reference fails soft with a diagnostic (references never fail the build). cache_days then only affects labelling — an expired-but-present cached inventory is served as stale (an informational diagnostic) rather than as a silent cache hit.

resolve_self

Type: string (default: "")

The name under which this project refers to itself, mirroring Sphinx’s intersphinx_resolve_self. A reference whose inventory qualifier equals this name resolves locally (the qualifier is stripped and the project’s own targets are consulted) instead of against an external inventory — for example, with resolve_self = "myproj", both a :ref: targeting myproj:some-label and the explicit :external+myproj:ref: role form resolve locally. Empty (the default) disables the behaviour. The self name takes precedence over a configured project of the same name, so avoid reusing an entry from [intersphinx.projects] here — that project would become unreachable via qualified references.

projects

Type: table (default: empty)

A table of external projects keyed by name ([intersphinx.projects.<name>]). The name is the prefix used by inventory-qualified lookups. Each project accepts:

url

Type: string (required)

Base URL of the external project’s documentation. Generated links are relative to this URL, and it must be unique across all configured projects.

inventories

Type: array of strings (default: derived from url)

Ordered inventory locations to try. Each entry is either a URL (it contains "://") or a filesystem path relative to the ubproject.toml directory. When omitted, the single location "<url>/objects.inv" is used.

Network-restricted CI

Because inventory fetches happen over the network, CI environments without outbound access should either set offline = true with committed local inventories files (the Doxygen-tagfile mode), or pre-warm the inventory cache before the run. Fetch failures are reported as warnings and never fail ubc check, so cross-project references simply fall back to placeholders if no inventory is available.