httk.core.docs.sphinx_ext¶

Sphinx glue for version labels, development warnings, and the selector UI.

The module itself has no Sphinx import dependency. Sphinx is imported only by setup(), allowing the rest of the documentation library to remain stdlib-only and usable by release workflows.

Functions¶

`document_label`(value)	Return a validated documentation label, defaulting to `dev:local`.
`channel_for_label`(label)	Return `release` for a version tag and `dev` for a development label.
`version_depth`(label)	Return the URL path depth used by the selector for label.
`selector_config_literal`(label)	Render the tiny JSON configuration literal consumed by `selector.js`.
`derive_internal_intersphinx_mapping`(mapping, config, ...)	Return mapping with declared internal dependencies versioned.
`setup`(app)	Register the extension with Sphinx and inject version-selector assets.

Module Contents¶

httk.core.docs.sphinx_ext.document_label(value)¶

Return a validated documentation label, defaulting to dev:local.

Parameters:: value (str | None) – Requested release or development label.
Returns:: Validated documentation label.
Raises:: ValueError – If value is not a supported label.
Return type:: str

httk.core.docs.sphinx_ext.channel_for_label(label)¶

Return release for a version tag and dev for a development label.

Parameters:: label (str) – Documentation label to classify.
Returns:: Channel associated with the label.
Return type:: Literal[‘release’, ‘dev’]

httk.core.docs.sphinx_ext.version_depth(label)¶

Return the URL path depth used by the selector for label.

Parameters:: label (str) – Documentation label whose URL depth is needed.
Returns:: Number of path components before a page URL.
Return type:: int

httk.core.docs.sphinx_ext.selector_config_literal(label)¶

Render the tiny JSON configuration literal consumed by selector.js.

Parameters:: label (str) – Documentation label to encode.
Returns:: JavaScript assignment containing selector configuration.
Raises:: ValueError – If label is not a supported documentation label.
Return type:: str

httk.core.docs.sphinx_ext.derive_internal_intersphinx_mapping(mapping, config, pins, base_url, label, *, temporary_inventory_dir=None, committed_inventory_dir=None)¶

Return mapping with declared internal dependencies versioned.

The function is deliberately side-effect free. The Sphinx callback fetches the development inventories separately, then supplies their paths here. dev:local is handled by the callback before this function is called so that the configuration object remains byte-for-byte untouched for local builds.

Parameters:

mapping (collections.abc.Mapping[str, tuple[str, str | list[str]]]) – Existing intersphinx mappings to copy and update.
config (httk.core.docs.config.VersioningConfig) – Configuration declaring internal dependencies.
pins (collections.abc.Mapping[str, str]) – Locked dependency versions for release mappings.
base_url (str) – Base URL containing dependency documentation sites.
label (str) – Release or development documentation label.
temporary_inventory_dir (str | pathlib.Path | None) – Directory for fetched development inventories.
committed_inventory_dir (str | pathlib.Path | None) – Directory containing committed release inventories.

Returns:

Mapping with internal dependency targets and inventories updated.

Raises:

ReleaseError – If a release dependency has no valid locked version.
ValueError – If the label or development inventory directory is invalid.

Return type:

dict[str, tuple[str, str | list[str]]]

httk.core.docs.sphinx_ext.setup(app)¶

Parameters:: app (object) – Sphinx application receiving the extension callbacks and assets.
Returns:: Sphinx extension metadata.
Return type:: dict[str, object]