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(→ str)	Return a validated documentation label, defaulting to dev:local.
channel_for_label(→ Literal[, ])	Return release for a version tag and dev for a development label.
version_depth(→ int)	Return the URL path depth used by the selector for label.
selector_config_literal(→ str)	Render the tiny JSON configuration literal consumed by selector.js.
derive_internal_intersphinx_mapping(→ dict[str, ...)	Return mapping with declared internal dependencies versioned.
setup(→ dict[str, object])	Register the extension with Sphinx and inject version-selector assets.

Module Contents

httk.core.docs.sphinx_ext.document_label(value: str | None) → str

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

httk.core.docs.sphinx_ext.channel_for_label(label: str) → Literal['release', 'dev']

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

httk.core.docs.sphinx_ext.version_depth(label: str) → int

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

httk.core.docs.sphinx_ext.selector_config_literal(label: str) → str

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

httk.core.docs.sphinx_ext.derive_internal_intersphinx_mapping(mapping: collections.abc.Mapping[str, tuple[str, str | list[str]]], config: httk.core.docs.config.VersioningConfig, pins: collections.abc.Mapping[str, str], base_url: str, label: str, *, temporary_inventory_dir: str | pathlib.Path | None = None, committed_inventory_dir: str | pathlib.Path | None = None) → dict[str, tuple[str, str | list[str]]]

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.

httk.core.docs.sphinx_ext.setup(app: object) → dict[str, object]

Register the extension with Sphinx and inject version-selector assets.