httk.core.docs

Shared versioned httk documentation machinery.

The package composes immutable release trees alongside replaceable dev:main trees, writes root/page manifests and redirects, validates locks and inventories, and supplies the Furo-aligned version selector used by published sites.

Submodules

• httk.core.docs.cli
• httk.core.docs.config
• httk.core.docs.ecosystem
• httk.core.docs.gitsite
• httk.core.docs.inventories
• httk.core.docs.lockfile
• httk.core.docs.manifests
• httk.core.docs.redirect
• httk.core.docs.release
• httk.core.docs.semver
• httk.core.docs.sitetree
• httk.core.docs.sphinx_ext

Exceptions

ConfigError	Raised when a versioning TOML file is missing, malformed, or unsafe.
EcosystemManifestError	Raised when an ecosystem checkout cannot produce a valid manifest.
GitSiteError	Raised when a generated site cannot be committed to a Git repository.
GitUnavailableError	Raised when the git executable is not available.
InventoryError	Raised when an inventory cannot be fetched or has unexpected metadata.
LockError	Raised when a documentation lock is absent, stale, or cannot be made.
ReleaseError	Raised when a release tag, project version, or documentation lock is invalid.
VersionError	Raised when text is not an exact X.Y.Z documentation version.
ComposeError	Raised when a documentation tree contains unsafe or unsupported entries.
ImmutabilityError	Raised when a rebuild differs from an already published release tree.

Classes

InternalDependency	Describe one internal httk distribution used by a documentation site.
VersioningConfig	Configure one versioned documentation site.
CommitSiteResult	Summarize a site commit operation.
ReleaseCheck	Summarize a successful release preflight.
Version	Represent one non-negative three-component documentation release version.
ComposeResult	Summarize one site composition operation.

Functions

load_versioning_config(path)	Read and validate a versioning TOML file, rejecting unknown keys.
build_ecosystem_manifest(submodules_dir, *[, ...])	Build the sorted manifest for direct Git checkouts under submodules_dir.
read_ecosystem_manifest(path)	Read a JSON manifest and report malformed files as typed errors.
verify_ecosystem_manifest(submodules_dir, manifest_path, *)	Verify a committed manifest against the current checkout state.
write_ecosystem_manifest(manifest, output)	Write manifest as sorted, newline-terminated JSON using an atomic replace.
commit_site(site_directory, branch, message, *[, ...])	Replace branch with one parentless commit containing site_directory.
fetch_inventory(url, dest, *[, expected_project, ...])	Fetch an inventory from HTTP(S) or file://, validate it, and save it.
read_inventory_header(path_or_bytes)	Return project and version from the plain-text inventory header.
check_lock(project_dir, lock_path)	Raise LockError if a lock is missing or stale for project_dir.
compute_input_hash(pyproject_path)	Hash the documentation dependency inputs, independent of TOML formatting.
filter_lock_pins(pins, *, drop)	Return pins excluding all httk-* names and the explicitly dropped names.
generate_lock(project_dir, output_path, *[, ...])	Generate a lock by invoking uv pip compile or an injected command.
internal_pins(pins)	Return the normalized subset of pins belonging to internal httk distributions.
read_lock_pins(lock_path)	Read normalized distribution names and versions from a lock file.
build_page_manifest(version_name, html_dir)	List every HTML page below html_dir as sorted POSIX paths.
build_version_manifest(slug, url, source_commit, ...)	Build a root manifest with releases newest-first and optional dev last.
read_version_manifest(path)	Read a JSON version manifest from path.
write_page_manifest(path, manifest)	Write one per-version page manifest.
write_version_manifest(path, manifest)	Write one JSON version manifest using stable, human-readable formatting.
root_redirect_html(target_relative_path)	Return a complete HTML5 document redirecting to a relative site path.
write_root_redirect(site_root, target)	Write index.html at site_root with a relative redirect to target.
check_release(project_dir, tag)	Validate a release tag against pyproject.toml and its docs lock.
dependency_doc_targets(config, pins, base_url, channel)	Derive exact release or dev/main inventory URLs for internal dependencies.
highest_version(versions)	Return the greatest version in versions, or None when empty.
is_release_dir_name(name)	Return whether name is a valid release directory such as v2.1.0.
parse_tag(text)	Parse exactly the release tag vX.Y.Z.
parse_version(text)	Parse exactly X.Y.Z without prerelease or build metadata.
compose_site(site_root, build_html, *, slug, site_url, ...)	Compose a docs-site tree while preserving releases and maintaining latest.

Package Contents

exception httk.core.docs.ConfigError

Bases: ValueError

Raised when a versioning TOML file is missing, malformed, or unsafe.

class httk.core.docs.InternalDependency

Describe one internal httk distribution used by a documentation site.

Parameters:

• distribution – Distribution name used by dependency metadata.

• slug – Documentation-site slug for the dependency.

• repository_url – Repository URL for the dependency.

• main_branch – Branch containing the dependency’s development docs.

distribution: str

slug: str

repository_url: str

main_branch: str = 'main'

class httk.core.docs.VersioningConfig

Configure one versioned documentation site.

Parameters:

• slug – Documentation-site slug.

• repository_url – Repository URL for the site.

• main_branch – Branch containing the site’s development docs.

• import_roots – Import roots whose documentation is generated.

• internal_dependencies – Internal distributions documented alongside the site.

slug: str

repository_url: str

main_branch: str = 'main'

import_roots: tuple[str, Ellipsis] = ()

internal_dependencies: tuple[InternalDependency, Ellipsis] = ()

httk.core.docs.load_versioning_config(path)

Read and validate a versioning TOML file, rejecting unknown keys.

Parameters:

path (str | pathlib.Path) – Versioning TOML file to read.

Returns:

Validated documentation-site configuration.

Raises:

ConfigError – If the file cannot be read or contains invalid configuration.

Return type:

VersioningConfig

exception httk.core.docs.EcosystemManifestError

Bases: RuntimeError

Raised when an ecosystem checkout cannot produce a valid manifest.

httk.core.docs.build_ecosystem_manifest(submodules_dir, *, require_release_tags=False)

Build the sorted manifest for direct Git checkouts under submodules_dir.

Parameters:

• submodules_dir (str | pathlib.Path) – Directory containing the expected direct checkouts.

• require_release_tags (bool) – Require each checkout tag to match its distribution version.

Returns:

Manifest describing the checked-out modules.

Raises:

EcosystemManifestError – If checkout structure, Git state, or release metadata is invalid.

Return type:

dict[str, object]

httk.core.docs.read_ecosystem_manifest(path)

Read a JSON manifest and report malformed files as typed errors.

Parameters:

path (str | pathlib.Path) – Manifest file to read.

Returns:

Validated ecosystem manifest.

Raises:

EcosystemManifestError – If the file cannot be read or has an invalid schema.

Return type:

dict[str, object]

httk.core.docs.verify_ecosystem_manifest(submodules_dir, manifest_path, *, require_release_tags=False)

Verify a committed manifest against the current checkout state.

Parameters:

• submodules_dir (str | pathlib.Path) – Directory containing the expected direct checkouts.

• manifest_path (str | pathlib.Path) – Committed manifest to compare with the checkout state.

• require_release_tags (bool) – Require each checkout tag to match its distribution version.

Raises:

EcosystemManifestError – If the checkout or manifest differs from the expected state.

httk.core.docs.write_ecosystem_manifest(manifest, output)

Write manifest as sorted, newline-terminated JSON using an atomic replace.

Parameters:

• manifest (collections.abc.Mapping[str, object]) – Ecosystem manifest to serialize.

• output (str | pathlib.Path) – Destination manifest path.

Raises:

EcosystemManifestError – If the destination cannot safely be written.

class httk.core.docs.CommitSiteResult

Summarize a site commit operation.

Parameters:

• repository – Repository receiving the generated objects.

• branch – Branch replaced by the new commit.

• commit – Identifier of the parentless commit.

• tree – Identifier of the committed site tree.

repository: pathlib.Path

branch: str

commit: str

tree: str

exception httk.core.docs.GitSiteError

Bases: RuntimeError

Raised when a generated site cannot be committed to a Git repository.

exception httk.core.docs.GitUnavailableError

Bases: GitSiteError

Raised when the git executable is not available.

httk.core.docs.commit_site(site_directory, branch, message, *, repository=None, author_name=None, author_email=None, committer_name=None, committer_email=None)

Replace branch with one parentless commit containing site_directory.

The site is converted directly into Git objects, so the caller’s index and checked-out files are not changed. Ref leases for concurrent publishers remain the caller’s responsibility when pushing the resulting branch. Git dates remain ambient, so commit IDs are intentionally not deterministic.

Parameters:

• site_directory (str | pathlib.Path) – Generated site tree to commit.

• branch (str) – Branch to replace with the generated commit.

• message (str) – Commit message for the generated commit.

• repository (str | pathlib.Path | None) – Repository to update, or the site/current repository.

• author_name (str | None) – Git author name, using the docs-bot default when omitted.

• author_email (str | None) – Git author email, using the docs-bot default when omitted.

• committer_name (str | None) – Git committer name, using the docs-bot default when omitted.

• committer_email (str | None) – Git committer email, using the docs-bot default when omitted.

Returns:

Identifiers and paths for the generated commit.

Raises:

• GitSiteError – If the site, repository, branch, or Git operation is invalid.

• GitUnavailableError – If the git executable is unavailable.

Return type:

CommitSiteResult

exception httk.core.docs.InventoryError

Bases: RuntimeError

Raised when an inventory cannot be fetched or has unexpected metadata.

httk.core.docs.fetch_inventory(url, dest, *, expected_project=None, expected_version=None)

Fetch an inventory from HTTP(S) or file://, validate it, and save it.

Parameters:

• url (str) – HTTP(S) or file:// URL of the inventory.

• dest (str | pathlib.Path) – Destination path for the validated inventory.

• expected_project (str | None) – Required project header, when supplied.

• expected_version (str | None) – Required version header, when supplied.

Returns:

Project and version declared by the fetched inventory.

Raises:

InventoryError – If fetching, validation, or saving the inventory fails.

Return type:

tuple[str, str]

httk.core.docs.read_inventory_header(path_or_bytes)

Return project and version from the plain-text inventory header.

Parameters:

path_or_bytes (str | pathlib.Path | bytes) – Inventory file path or its contents.

Returns:

Project and version declared by the inventory.

Raises:

InventoryError – If the inventory does not have the expected header.

Return type:

tuple[str, str]

exception httk.core.docs.LockError

Bases: RuntimeError

Raised when a documentation lock is absent, stale, or cannot be made.

httk.core.docs.check_lock(project_dir, lock_path)

Raise LockError if a lock is missing or stale for project_dir.

Parameters:

• project_dir (str | pathlib.Path) – Project directory whose dependency inputs are checked.

• lock_path (str | pathlib.Path) – Lock path, relative to the project directory when relative.

Raises:

LockError – If the lock is missing, malformed, stale, or has invalid pins.

httk.core.docs.compute_input_hash(pyproject_path)

Hash the documentation dependency inputs, independent of TOML formatting.

Parameters:

pyproject_path (str | pathlib.Path) – Project metadata file containing the dependency inputs.

Returns:

SHA-256 digest of the canonicalized lock inputs.

Raises:

LockError – If the project metadata or dependency inputs are invalid.

Return type:

str

httk.core.docs.filter_lock_pins(pins, *, drop)

Return pins excluding all httk-* names and the explicitly dropped names.

Parameters:

• pins (collections.abc.Mapping[str, str]) – Distribution pins to normalize and filter.

• drop (collections.abc.Iterable[str]) – Additional distribution names to exclude.

Returns:

Filtered pins keyed by normalized distribution name.

Return type:

dict[str, str]

httk.core.docs.generate_lock(project_dir, output_path, *, command_prefix=None)

Generate a lock by invoking uv pip compile or an injected command.

Parameters:

• project_dir (str | pathlib.Path) – Project directory containing pyproject.toml.

• output_path (str | pathlib.Path) – Lock path, relative to the project directory when relative.

• command_prefix (collections.abc.Sequence[str] | None) – Command to invoke instead of uv.

Raises:

LockError – If inputs are invalid, compilation fails, or the lock cannot be written.

httk.core.docs.internal_pins(pins)

Return the normalized subset of pins belonging to internal httk distributions.

Parameters:

pins (collections.abc.Mapping[str, str]) – Distribution pins to normalize and filter.

Returns:

Pins whose normalized names start with httk-.

Return type:

dict[str, str]

httk.core.docs.read_lock_pins(lock_path)

Read normalized distribution names and versions from a lock file.

Parameters:

lock_path (str | pathlib.Path) – Lock file to read.

Returns:

Mapping of normalized distribution names to pinned versions.

Return type:

dict[str, str]

httk.core.docs.build_page_manifest(version_name, html_dir)

List every HTML page below html_dir as sorted POSIX paths.

Parameters:

• version_name (str) – Version name recorded in the manifest.

• html_dir (str | pathlib.Path) – Root directory containing generated HTML.

Returns:

Per-version page manifest.

Return type:

dict[str, Any]

httk.core.docs.build_version_manifest(slug, url, source_commit, release_versions, has_dev)

Build a root manifest with releases newest-first and optional dev last.

The default release points to the maintained latest/ duplicate of the newest release tree.

Parameters:

• slug (str) – Documentation-site project slug.

• url (str) – Public documentation-site URL.

• source_commit (str | None) – Source commit represented by the site, when known.

• release_versions (list[httk.core.docs.semver.Version] | tuple[httk.core.docs.semver.Version, Ellipsis]) – Published release versions.

• has_dev (bool) – Whether the replaceable development site is published.

Returns:

Root version manifest.

Return type:

dict[str, Any]

httk.core.docs.read_version_manifest(path)

Read a JSON version manifest from path.

Parameters:

path (str | pathlib.Path) – Manifest file to read.

Returns:

Parsed version manifest.

Raises:

ValueError – If the JSON value is not an object.

Return type:

dict[str, Any]

httk.core.docs.write_page_manifest(path, manifest)

Write one per-version page manifest.

Parameters:

• path (str | pathlib.Path) – Destination manifest path.

• manifest (dict[str, Any]) – Manifest to serialize.

httk.core.docs.write_version_manifest(path, manifest)

Write one JSON version manifest using stable, human-readable formatting.

Parameters:

• path (str | pathlib.Path) – Destination manifest path.

• manifest (dict[str, Any]) – Manifest to serialize.

httk.core.docs.root_redirect_html(target_relative_path)

Return a complete HTML5 document redirecting to a relative site path.

Parameters:

target_relative_path (str) – Relative path receiving the redirect.

Returns:

HTML redirect document.

Return type:

str

httk.core.docs.write_root_redirect(site_root, target)

Write index.html at site_root with a relative redirect to target.

Parameters:

• site_root (str | pathlib.Path) – Site root receiving the redirect file.

• target (str) – Relative path receiving the redirect.

class httk.core.docs.ReleaseCheck

Summarize a successful release preflight.

Parameters:

• tag – Release tag validated by the preflight.

• version – Parsed release version.

• lock_path – Documentation lock checked by the preflight.

tag: str

version: httk.core.docs.semver.Version

lock_path: pathlib.Path

exception httk.core.docs.ReleaseError

Bases: RuntimeError

Raised when a release tag, project version, or documentation lock is invalid.

httk.core.docs.check_release(project_dir, tag)

Validate a release tag against pyproject.toml and its docs lock.

Parameters:

• project_dir (str | pathlib.Path) – Project directory containing release metadata.

• tag (str) – Release tag to validate.

Returns:

Summary of the successful release preflight.

Raises:

ReleaseError – If project metadata, the release tag, lock, or inventories are invalid.

Return type:

ReleaseCheck

httk.core.docs.dependency_doc_targets(config, pins, base_url, channel)

Derive exact release or dev/main inventory URLs for internal dependencies.

Parameters:

• config (httk.core.docs.config.VersioningConfig) – Documentation-site configuration declaring the dependencies.

• pins (collections.abc.Mapping[str, str]) – Locked distribution versions used for release URLs.

• base_url (str) – Base URL containing the dependency documentation sites.

• channel (str) – Documentation channel, either release or dev.

Returns:

Mapping of dependency distributions to inventory base URLs.

Raises:

• ReleaseError – If a release dependency has no valid locked version.

• ValueError – If channel or a locked dependency version is invalid.

Return type:

dict[str, str]

class httk.core.docs.Version

Represent one non-negative three-component documentation release version.

Parameters:

• major – Major release component.

• minor – Minor release component.

• patch – Patch release component.

Raises:

VersionError – If a component is negative, non-integral, or boolean.

major: int

minor: int

patch: int

property tag: str

Return the canonical Git tag spelling, vX.Y.Z.

exception httk.core.docs.VersionError

Bases: ValueError

Raised when text is not an exact X.Y.Z documentation version.

httk.core.docs.highest_version(versions)

Return the greatest version in versions, or None when empty.

Parameters:

versions (collections.abc.Iterable[Version]) – Versions to compare.

Returns:

Greatest version, or None when the iterable is empty.

Return type:

Version | None

httk.core.docs.is_release_dir_name(name)

Return whether name is a valid release directory such as v2.1.0.

Parameters:

name (str) – Directory name to validate.

Returns:

Whether name is an exact release tag spelling.

Return type:

bool

httk.core.docs.parse_tag(text)

Parse exactly the release tag vX.Y.Z.

Parameters:

text (str) – Git tag spelling to validate.

Returns:

Parsed release version.

Raises:

VersionError – If text is not an exact vX.Y.Z tag.

Return type:

Version

httk.core.docs.parse_version(text)

Parse exactly X.Y.Z without prerelease or build metadata.

Parameters:

text (str) – Version spelling to validate.

Returns:

Parsed release version.

Raises:

VersionError – If text is not an exact X.Y.Z version.

Return type:

Version

exception httk.core.docs.ComposeError

Bases: RuntimeError

Raised when a documentation tree contains unsafe or unsupported entries.

class httk.core.docs.ComposeResult

Summarize one site composition operation.

Parameters:

• changed – Whether any generated site file changed.

• unchanged – Whether the requested target tree already matched.

• default_target – Manifest name selected as the site’s default.

• versions – All published version labels, including development channels.

changed: bool

unchanged: bool

default_target: str

versions: tuple[str, Ellipsis]

exception httk.core.docs.ImmutabilityError

Bases: RuntimeError

Raised when a rebuild differs from an already published release tree.

httk.core.docs.compose_site(site_root, build_html, *, slug, site_url, source_commit, target, repair=False)

Compose a docs-site tree while preserving releases and maintaining latest.

The root redirect lands on latest/ when a release exists; latest/ is a replaceable duplicate of the newest release tree.

repair=True is reserved for replacing an existing release after an approved manual repair. The replacement uses the same rename transaction as the development swap and never removes the live release in place.

Parameters:

• site_root (pathlib.Path) – Root directory of the composed documentation site.

• build_html (pathlib.Path) – Generated HTML tree to publish.

• slug (str) – Site slug stored in the version manifest.

• site_url (str) – Public site URL stored in the version manifest.

• source_commit (str | None) – Source commit recorded in the version manifest.

• target (httk.core.docs.semver.Version | Literal['dev']) – Release version or the replaceable development target.

• repair (bool) – Whether to replace an existing release after manual approval.

Returns:

Summary of the composition result.

Raises:

• ComposeError – If the source, destination, or target is unsafe or invalid.

• ImmutabilityError – If an existing release differs from the rebuilt tree.

Return type:

ComposeResult