Module intersphinx 

sphinx.ext.intersphinx — cross-project references resolved through other projects’ objects.inv inventories.

Ported from Sphinx 9.1.0’s sphinx/ext/intersphinx/ (_load.py, _resolve.py, _shared.py); every message text, ordering rule and fallback below is cited to the file:line it mirrors, collected in docs/superpowers/plans/2026-08-31-m2-wave4-research-spec-inventory-intersphinx.md §3-§4.

The three phases, in the order a build runs them:

1. Validation (validate_mapping) normalises intersphinx_mapping at configuration load. Any failure is a ConfigError in Sphinx, which aborts the build — here it aborts config loading, which the CLI turns into exit code 2.
2. Loading (load_mappings) reads each project’s inventory: local files always, remote ones through an InventoryFetcher with an on-disk cache. The merged “main” inventory plus the per-name ones are the IntersphinxData.
3. Resolution (Intersphinx::resolve_detect and friends) runs from the reference resolver, standing exactly where Sphinx’s missing-reference event does: after the local domain has failed and before the dangling-reference warning.

Re-exports

pub use fetch::HttpConfig;

pub use fetch::InventoryFetcher;

pub use fetch::TlsCacerts;

pub use fetch::UreqFetcher;

pub use fetch::DEFAULT_USER_AGENT;

Modules

fetch

The one place intersphinx touches the network, behind a trait so every test can stay offline.

Structs

Diagnostic

A diagnostic resolution wants logged, with the type.subtype category Sphinx gives it.

Intersphinx

The loaded inventories plus the two configuration values resolution consults.

IntersphinxData

The loaded inventories: the merged “main” one every un-named lookup goes through, and the per-project ones an inv:target or :external+inv: reference names (_shared.py:114-149, InventoryAdapter).

LoadOutcome

What loading produced, plus the diagnostics it wants reported.

LoadRequest

Everything load_mappings needs from the build.

Resolution

A reference into another project.

XrefQuery

The pending_xref attributes resolution reads.

Enums

ExternalRole

What the parse layer should build for an :external:...: role.

HookOutcome

What the missing-reference hook decided.

Constants

CACHE_DIR_NAME

The on-disk cache directory, relative to the doctree/cache directory (app.doctreedir / '__intersphinx_cache__', _load.py:186-190). Sphinx documents that “the location of this cache directory must not be relied upon externally”; ours rides the fingerprint-wiped cache dir, so a configuration change clears it along with everything else.

Functions

domain_and_role

_get_domain_role (_resolve.py:508-521): no colon is a bare role name, one colon splits domain from role, two or more is unusable.

external_inventory_missing

The inventory-existence check IntersphinxRole.run makes first (_resolve.py:385-390), deferred to resolution time because that is where this port knows what got loaded.

external_not_found

The failure IntersphinxRoleResolver reports for a stamped node nothing matched (_resolve.py:557-565), logged with type='ref' and subtype=reftype.

external_role

The role-name half of IntersphinxRole.run (_resolve.py:378-463), minus the inventory-existence check — that one needs the loaded inventories, and is applied at resolution time by external_inventory_missing so its warning still wins the race Sphinx gives it (it is checked first).

inventory_and_name_suffix

get_inventory_and_name_suffix (_resolve.py:486-506): split external[+inv]:suffix into its inventory name and domain:name suffix.

is_external_role

Whether a role name is one IntersphinxDispatcher claims (_resolve.py:358-366). The name is the one the author wrote: the inventory name inside it is case-sensitive.

load_mappings

Read every configured inventory (load_mappings, _load.py:139-208).

mapping_config_error

The ConfigError Sphinx raises once validation has logged its errors (_load.py:131-136).

redirect_target_uri

The redirect rule (_load.py:410-419), kept pure: after a fetch that ended somewhere other than where it started, the target URI is rewritten only when it was pointing at the inventory’s own directory.

safe_url

_get_safe_url (_load.py:439-461): the password is dropped from a user:password@host URL before it reaches a log line.

strip_basic_auth

_strip_basic_auth (_load.py:464-482): user[:pass]@hostname in the netloc becomes hostname.

validate_mapping

Validate and normalise a raw intersphinx_mapping value as parsed from conf.py, returning the entries that survived and the error messages for the ones that did not.

Type Aliases

IntersphinxMapping

The normalised intersphinx_mapping: project name -> (target URI, inventory locations). Sphinx stores {name: (name, (uri, locations))} with the name duplicated inside the value (_load.py:129); the key is the same string, so this drops the duplicate.