httk.core.docs.sitetree

Compose immutable release and replaceable development documentation trees.

Exceptions

ComposeError	Raised when a documentation tree contains unsafe or unsupported entries.
ImmutabilityError	Raised when a rebuild differs from an already published release tree.

Classes

ComposeResult

Summarize one site composition operation.

Functions

compose_site(site_root, build_html, *, slug, site_url, ...)

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

Module Contents

exception httk.core.docs.sitetree.ComposeError

Bases: RuntimeError

Raised when a documentation tree contains unsafe or unsupported entries.

exception httk.core.docs.sitetree.ImmutabilityError

Bases: RuntimeError

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

class httk.core.docs.sitetree.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]

httk.core.docs.sitetree.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