Sphinx Builder Helpers

Module: thornforge.buildsite.builder

Overview

Builder helpers run Sphinx, patch target conf.py files, copy shared assets, inject documentation page assets, and create public symlinks to canonical build outputs.

Autodoc

thornforge.buildsite.builder.build_docs(worktree: Path, docs_source_dir: Path, output_dir: Path) → None

Run a single Sphinx HTML build.

Parameters:

• worktree – Root directory of the extracted repository snapshot. This path is added to PYTHONPATH so project-local imports in conf.py continue to work during the Sphinx build.

• docs_source_dir – Directory that contains the project’s Sphinx sources, including conf.py and the documentation documents.

• output_dir – Destination directory for generated HTML. Any existing directory at this path is removed before Sphinx is invoked.

Side Effects:

Deletes and recreates output_dir. Spawns a python -m sphinx -b html subprocess.

Returns:

None. The generated documentation is written to output_dir.

thornforge.buildsite.builder.copy_shared_site_assets(output_dir: Path) → None

Copy ThornForge-owned assets into a site tree.

Parameters:

output_dir – Directory that should receive an assets/ subtree.

Side Effects:

Removes any pre-existing output_dir / "assets" directory and copies ThornForge’s bundled asset tree into its place.

Returns:

None. Assets are copied onto disk.

thornforge.buildsite.builder.inject_built_docs_assets(docs_output_dir: Path) → None

Post-process generated docs HTML so ThornForge assets are referenced.

Parameters:

docs_output_dir – Root directory containing generated documentation HTML for a single built version.

Side Effects:

Copies ThornForge’s shared assets into docs_output_dir / "assets" and rewrites each HTML file in place so it links to the shared stylesheets and JavaScript files.

Returns:

None. Updated HTML is written back to disk.

thornforge.buildsite.builder.inject_shared_navigation(docs_root: Path) → None

Patch a target conf.py to enable ThornForge’s shared docs navigation.

Parameters:

docs_root – Sphinx source directory containing the target project’s conf.py file.

Side Effects:

Appends a guarded configuration block to conf.py so the build uses ThornForge’s shared versions.html template and ensures the sidebar configuration includes the version switcher.

Returns:

None. The function mutates docs_root / "conf.py" in place unless the injected marker already exists.

Raises:

FileNotFoundError – If docs_root does not exist.

thornforge.buildsite.builder.make_relative_symlink(target: Path, link_path: Path) → None

Create or replace a directory symlink using a relative target path.

Parameters:

• target – Existing directory that the symlink should point to.

• link_path – Filesystem location where the symlink should be created.

Side Effects:

Deletes any pre-existing file, symlink, or directory at link_path and replaces it with a relative symlink to target.

Returns:

None. The symlink is created on disk.