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	Documentation-site metadata for one internal httk distribution.
VersioningConfig	Configuration for one versioned documentation site.
CommitSiteResult	Summary of a site commit operation.
ReleaseCheck	Summary of a successful release preflight.
Version	One non-negative three-component documentation release version.
ComposeResult	Summary of one site composition operation.

Functions

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

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

Documentation-site metadata for one internal httk distribution.

distribution: str

slug: str

repository_url: str

main_branch: str = 'main'

class httk.core.docs.VersioningConfig

Configuration for one versioned documentation 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: str | pathlib.Path) → VersioningConfig

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

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: str | pathlib.Path, *, require_release_tags: bool = False) → dict[str, object]

Build the sorted manifest for direct Git checkouts under submodules_dir.

httk.core.docs.read_ecosystem_manifest(path: str | pathlib.Path) → dict[str, object]

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

httk.core.docs.verify_ecosystem_manifest(submodules_dir: str | pathlib.Path, manifest_path: str | pathlib.Path, *, require_release_tags: bool = False) → None

Verify a committed manifest against the current checkout state.

httk.core.docs.write_ecosystem_manifest(manifest: collections.abc.Mapping[str, object], output: str | pathlib.Path) → None

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

class httk.core.docs.CommitSiteResult

Summary of a site commit operation.

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: str | pathlib.Path, branch: str, message: str, *, repository: str | pathlib.Path | None = None, author_name: str | None = None, author_email: str | None = None, committer_name: str | None = None, committer_email: str | None = None) → CommitSiteResult

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.

exception httk.core.docs.InventoryError

Bases: RuntimeError

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

httk.core.docs.fetch_inventory(url: str, dest: str | pathlib.Path, *, expected_project: str | None = None, expected_version: str | None = None) → tuple[str, str]

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

httk.core.docs.read_inventory_header(path_or_bytes: str | pathlib.Path | bytes) → tuple[str, str]

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

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: str | pathlib.Path, lock_path: str | pathlib.Path) → None

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

httk.core.docs.compute_input_hash(pyproject_path: str | pathlib.Path) → str

Hash the documentation dependency inputs, independent of TOML formatting.

httk.core.docs.filter_lock_pins(pins: collections.abc.Mapping[str, str], *, drop: collections.abc.Iterable[str]) → dict[str, str]

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

httk.core.docs.generate_lock(project_dir: str | pathlib.Path, output_path: str | pathlib.Path, *, command_prefix: collections.abc.Sequence[str] | None = None) → None

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

httk.core.docs.internal_pins(pins: collections.abc.Mapping[str, str]) → dict[str, str]

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

httk.core.docs.read_lock_pins(lock_path: str | pathlib.Path) → dict[str, str]

Read normalized distribution names and versions from a lock file.

httk.core.docs.build_page_manifest(version_name: str, html_dir: str | pathlib.Path) → dict[str, Any]

List every HTML page below html_dir as sorted POSIX paths.

httk.core.docs.build_version_manifest(slug: str, url: str, source_commit: str | None, release_versions: list[httk.core.docs.semver.Version] | tuple[httk.core.docs.semver.Version, Ellipsis], has_dev: bool) → dict[str, Any]

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

httk.core.docs.read_version_manifest(path: str | pathlib.Path) → dict[str, Any]

Read a JSON version manifest from path.

httk.core.docs.write_page_manifest(path: str | pathlib.Path, manifest: dict[str, Any]) → None

Write one per-version page manifest.

httk.core.docs.write_version_manifest(path: str | pathlib.Path, manifest: dict[str, Any]) → None

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

httk.core.docs.root_redirect_html(target_relative_path: str) → str

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

httk.core.docs.write_root_redirect(site_root: str | pathlib.Path, target: str) → None

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

class httk.core.docs.ReleaseCheck

Summary of a successful release 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: str | pathlib.Path, tag: str) → ReleaseCheck

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

httk.core.docs.dependency_doc_targets(config: httk.core.docs.config.VersioningConfig, pins: collections.abc.Mapping[str, str], base_url: str, channel: str) → dict[str, str]

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

class httk.core.docs.Version

One non-negative three-component documentation release version.

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: collections.abc.Iterable[Version]) → Version | None

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

httk.core.docs.is_release_dir_name(name: str) → bool

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

httk.core.docs.parse_tag(text: str) → Version

Parse exactly the release tag vX.Y.Z.

httk.core.docs.parse_version(text: str) → Version

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

exception httk.core.docs.ComposeError

Bases: RuntimeError

Raised when a documentation tree contains unsafe or unsupported entries.

class httk.core.docs.ComposeResult

Summary of one site composition operation.

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: pathlib.Path, build_html: pathlib.Path, *, slug: str, site_url: str, source_commit: str | None, target: httk.core.docs.semver.Version | Literal['dev'], repair: bool = False) → ComposeResult

Compose a docs-site tree while preserving all existing release directories.

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.