Site Assembly

Module: thornforge.buildsite.site

Overview

Site assembly writes generated homepage content, rendered project metadata pages, docs redirect files, JSON manifests, symlinks, and inline runtime payloads for generated HTML.

Autodoc

thornforge.buildsite.site.build_inline_json_script(script_id: str, payload: object) → str

Serialize a Python object into an inline JSON <script> tag.

Parameters:

  • script_id – DOM id assigned to the generated script element.

  • payload – JSON-serializable object to embed.

Returns:

HTML string containing a <script type="application/json"> block.

thornforge.buildsite.site.collect_site_nav_pages(output_dir: Path) → list[dict[str, str]]

Collect root-level HTML pages for the runtime site navigation.

Parameters:

output_dir – Generated site root to scan.

Returns:

A sorted list of dictionaries containing label and path keys for non-docs HTML pages that should appear in the top navigation.

thornforge.buildsite.site.embed_runtime_data(output_dir: Path, site_nav_payload: dict[str, object], versions_payload: dict[str, object]) → None

Embed JSON runtime payloads directly into generated HTML files.

Parameters:

  • output_dir – Site root whose HTML files should be post-processed.

  • site_nav_payload – Navigation payload that every rendered page can use.

  • versions_payload – Version payload used only by docs pages.

Side Effects:

Rewrites generated HTML files in place to add inline JSON payloads when those payloads are not already present.

Returns:

None.

thornforge.buildsite.site.extract_html_title(html_path: Path) → str | None

Extract the first <title> from an HTML file.

Parameters:

html_path – Path to an HTML file that has already been written to disk.

Returns:

Decoded title text if a title element is present and non-empty, otherwise None.

thornforge.buildsite.site.inject_inline_json_scripts(document: str, scripts: list[str]) → str

Insert inline JSON script blocks into an existing HTML document.

Parameters:

  • document – Existing HTML document text.

  • scripts – Pre-rendered script tag strings to insert.

Returns:

Updated HTML with the script tags inserted before </body> when that closing tag exists, or appended to the end otherwise.

thornforge.buildsite.site.label_from_output_path(output_path: Path) → str

Convert a generated output path into a human-friendly navigation label.

Parameters:

output_path – Path relative to the site root for a generated HTML page.

Returns:

Title-cased label text derived from the path, with special handling for index.html pages.

thornforge.buildsite.site.render_project_page_body(source_path: Path) → tuple[str, str]

Convert one project metadata file into wrapped-page inputs.

Parameters:

source_path – Source metadata file such as README.rst or CHANGELOG.txt.

Returns:

Tuple of (title, body_html) suitable for wrap_info_html_document.

thornforge.buildsite.site.render_project_site_pages(repo_root: Path, output_dir: Path, project_pages: tuple[tuple[Path, Path], ...]) → None

Render metadata files such as README and CHANGELOG into site pages.

Parameters:

  • repo_root – Repository root containing the source metadata files.

  • output_dir – Root directory of the generated site.

  • project_pages – Sequence of (source_relative_path, output_relative_path) pairs describing which files should be published and where.

Side Effects:

Writes wrapped HTML pages into output_dir.

Returns:

None.

thornforge.buildsite.site.write_docs_site_files(docs_dir: Path, versions: list[str], digests: dict[str, str]) → dict[str, object]

Write docs-level helper files such as redirects and version metadata.

Parameters:

  • docs_dir – Root docs directory inside the generated site.

  • versions – Ordered version labels that were built.

  • digests – Mapping from version label to canonical build digest.

Side Effects:

Writes versions.json, a redirecting docs index.html, and the latest symlink inside docs_dir.

Returns:

The Python payload object that was serialized to versions.json.

thornforge.buildsite.site.write_homepage(output_dir: Path, latest: str, project_name: str) → None

Render the generated site homepage from a shared HTML template.

Parameters:

  • output_dir – Generated site root where index.html should be written.

  • latest – Latest version label used to populate docs links.

  • project_name – Display name inserted into the homepage title and hero.

Side Effects:

Writes output_dir / "index.html".

Returns:

None.

thornforge.buildsite.site.write_site_nav_manifest(output_dir: Path, latest: str, project_name: str) → dict[str, object]

Write the top-navigation manifest used by the frontend scripts.

Parameters:

  • output_dir – Generated site root where site-nav.json should be written.

  • latest – Latest version label that should be exposed in nav metadata.

  • project_name – Display name used for the top-navigation brand.

Returns:

The Python payload object that was serialized to site-nav.json.