Architecture

The build pipeline is intentionally split into small filesystem-oriented modules. The high-level orchestration lives in thornforge.buildsite.build_site.

Build flow

  1. Materialize the source repository. Local paths are used directly; supported GitHub URLs are cloned into a temporary directory.

  2. Discover the repository profile: docs directory, project name, project pages, version fallback, Git capability, and hash input paths.

  3. Choose build versions from v* Git tags, or fall back to one current-tree build.

  4. Copy or archive each version into a temporary worktree.

  5. Patch the Sphinx conf.py with ThornForge’s version-switcher sidebar configuration.

  6. Run python -m sphinx -b html.

  7. Copy shared assets and inject navigation/runtime references into generated HTML.

  8. Write public version symlinks, latest, JSON manifests, project pages, and inline runtime payloads.

Module boundaries

thornforge.buildsite.repository

Discovers source repository structure and metadata.

thornforge.buildsite.git

Wraps Git commands, source materialization, and content hashing.

thornforge.buildsite.builder

Runs Sphinx and post-processes documentation build outputs.

thornforge.buildsite.site

Writes generated site pages, docs helper files, and runtime JSON payloads.

thornforge.buildsite.info_site

Publishes optional info/ content into the root of the generated site.

thornforge.buildsite.nav

Normalizes HTML fragments and injects shared navigation placeholders, CSS, and JavaScript references.