Build Orchestration

Module: thornforge.buildsite.build_site

Overview

This module coordinates the full static site build: source materialization, repository discovery, version selection, Sphinx builds, asset injection, site page rendering, and runtime metadata embedding.

Important API

build_versioned_site(source, output_dir)

Build a complete static site from a local repository path or supported GitHub URL into output_dir.

collect_build_versions(repo_root, default_version_name, is_git_repo)

Return the ordered documentation versions ThornForge should build.

collect_tags(repo_root)

Return matching release tags sorted by PEP 440 version rules.

Autodoc

class thornforge.buildsite.build_site.BuildVersion(name: str, ref: str | None)

Describe one logical documentation build target.

name

Human-readable version label written into the output tree, such as v1.2.0 or current.

Type:

str

ref

Git reference used to materialize the source tree for this build. This is None when ThornForge should build directly from the current working tree instead of a tagged archive.

Type:

str | None

name: str

ref: str | None

thornforge.buildsite.build_site.build_versioned_site(source: str | Path, output_dir: Path) → None

Build the final static site into output_dir.

Parameters:

• source – Either a local repository path or a GitHub URL. Local paths are used directly; remote URLs are cloned into a temporary directory before discovery and build steps begin.

• output_dir – Destination directory for the assembled site. The directory is deleted and recreated before the build so the result is fully deterministic.

Side Effects:

Removes any existing output_dir. Writes built documentation, copied assets, JSON manifests, and symlinks under output_dir.

Returns:

None. The result is the generated site tree on disk.

thornforge.buildsite.build_site.collect_build_versions(repo_root: Path, default_version_name: str, is_git_repo: bool) → list[BuildVersion]

Determine which logical versions ThornForge should build.

Parameters:

• repo_root – Repository root used to inspect Git tags when available.

• default_version_name – Fallback version label for repositories that do not expose matching release tags.

• is_git_repo – Whether repo_root is a readable Git repository.

Returns:

A non-empty list of BuildVersion objects. Tagged repositories return one entry per v* tag. Non-Git repositories or repositories without matching tags return a single entry pointing at the current checkout.

thornforge.buildsite.build_site.collect_tags(repo_root: Path) → list[str]

Return documentation tags sorted in ascending version order.

Parameters:

repo_root – Repository root used as the working directory for git.

Returns:

A list of tag names matching v* sorted with packaging.version so later release tags appear later in the list.

Raises:

SystemExit – If any matching tag cannot be parsed as a PEP 440 version after removing the leading v.

thornforge.buildsite.build_site.parse_version_tag(tag: str) → Version

Parse a Git tag into a packaging.version.Version instance.

Parameters:

tag – Raw Git tag text, expected to use the common vX.Y.Z form.

Returns:

A parsed Version object used for deterministic sorting.