Skip to content

livery.extensions.docs._site

livery.extensions.docs._site

The documentation site: its rendered config, mounts, and verbs.

One rendered site per workspace. The config zensical reads is assembled by the build, into a gitignored zensical.toml at the root: the site's identity from the contract, the root pages, and one section per package from the nav each package emits into its own generated tree. Nothing committed enumerates the packages. Authors write packages/<name>/docs/ and the root docs/ tree; every underscore path this module writes is machine territory, refreshed by the verbs and never edited by a person. The tables a listed extension adds to the config, the handler of an API reference among them, are its answer to the docs.config query, joined after the docs extension's own.

A package owns the shape of its own site section through docs/nav.toml: a hand-authored tree the emitter merges under that package's section of the rendered root config, checked both ways (an entry naming a missing page refuses, and so does an authored page absent from the nav). A generator owns a block between markers in that tree (tasks, tools), and the emitter's sections, Changelog, Coverage and API, are marker blocks too, which the author may place; one the author did not place lands in that order, the changelog and coverage entries ahead of the tasks block and the API after everything. The API entries are the block a step of the docs phase emits into the package's generated tree, as a generator emits its own. A package without a nav.toml gets its pages enumerated, index first, and the machine sections in the same order. fm docs.build --package <name> builds a scoped preview of one section into the gitignored .docs-preview/ directory; the workspace site stays the only deploy artifact.

Functions:

Name Description
package_coverage_reports

The coverage reports package declares: (label, path) each.

generate_coverage_pages

Copy declared coverage trees and write each coverage page.

refresh_site_coverage

Put each package's coverage trees into the built site; the packages refreshed.

package_nav

The package's authored nav tree, or None without a nav.toml.

authored_nav

The authored tree with its placed blocks as sentinels, and each block's entries.

check_package_nav

Refuse an authored nav that disagrees with the docs tree.

abbreviation_files

Every package's committed glossary, for the site-wide append.

package_docs_extras

The css and javascript a package's [docs] table declares.

stage_extension_assets

Copy every extension's site assets under docs/_extensions/; those staged.

theme_values

The theme block's values the listed extensions answer, by key.

zensical_config

The assembled zensical.toml body, header excluded.

packages_nav_lines

The nav's one Packages entry: the landing page, then the tree.

changelog_page

The package's changelog page; None without a changelog.

generate_changelog_pages

Write each package's changelog page into its generated tree; the names.

release_years

The archive years the view paginates into, newest first.

generate_release_pages

Write the site-wide release view; the page paths written.

section_digest

A digest of a package's docs tree: every file's path and bytes.

mount_package_docs

Mount every package's docs/ into the site tree; the names copied.

published_url

The URL path a markdown page publishes at with directory URLs.

named_package

The package whose directory is name; refuses naming the known.

scoped_config

The scoped preview's config body: chrome plus one section.

materialise_preview

Materialise one package's preview tree; the scoped config's path.

run_site_phase

Run the steps registered for phase over the workspace at root.

emit_section_navs

Emit each package's complete section nav into its generated tree; the names.

write_site_config

Assemble the config zensical reads and write it to the root; the path.

clear_generated

Remove the generated trees an earlier build left: the root's and each package's.

docs_build

Mount every package's docs, assemble the config, and build the site, strict.

require_sources

Refuse before the build when the site's sources are not in the checkout.

source_summary

One line on what the build reads: the pages under docs/.

generator_lines

The generator's own output, indented, for a run in CI; nothing otherwise.

require_site

Refuse when the build left no site to publish.

docs_publish

Run the deploy phase on the built site, then publish it through the seam.

docs_serve

Mount every package's docs and serve the site live.

section_title

The page title of a prose section: its name, capitalised.

development_content

Each section's markdown for a human reader, in section order, empty left out.

generate_development_pages

Write the development section, one page per prose section; the pages written.

development_nav_lines

The nav entry for the development section, empty without a section to show.

Attributes:

Name Type Description
SITE_CONFIG
SITE_TREES
EMITTED_BLOCKS
API_BLOCK
SENTINEL
WORKSPACE_CSS
RELEASES
BUILD_DIR
COVERAGE_TREE
PREVIEW
PREVIEW_ROOT
DOCS_PHASE
DEPLOY_PHASE
docs_group
DEVELOPMENT

SITE_CONFIG module-attribute

SITE_CONFIG = 'zensical.toml'

SITE_TREES module-attribute

SITE_TREES = ('packages', 'releases', 'tasks', 'tools', 'development')

EMITTED_BLOCKS module-attribute

EMITTED_BLOCKS = ('changelog', 'coverage', 'api')

API_BLOCK module-attribute

API_BLOCK = 'api'

SENTINEL module-attribute

SENTINEL = 'nav:'

WORKSPACE_CSS module-attribute

WORKSPACE_CSS = ('assets/site.css',)

RELEASES module-attribute

RELEASES = 'docs/releases'

BUILD_DIR module-attribute

BUILD_DIR = '.docs-build'

COVERAGE_TREE module-attribute

COVERAGE_TREE = f'{GENERATED}coverage/'

PREVIEW module-attribute

PREVIEW = '.docs-preview'

PREVIEW_ROOT module-attribute

PREVIEW_ROOT = '../..'

DOCS_PHASE module-attribute

DOCS_PHASE = 'docs'

DEPLOY_PHASE module-attribute

DEPLOY_PHASE = 'deploy'

docs_group module-attribute

docs_group = group('docs', help="The workspace's documentation site")

DEVELOPMENT module-attribute

DEVELOPMENT = 'docs/development'

package_coverage_reports

package_coverage_reports(package: Package) -> list[tuple[str, str]]

The coverage reports package declares: (label, path) each.

The [docs] table's coverage list: a label and the package-relative path where the package's own tooling writes a static HTML tree. The toolchain never learns the producing tool; coverage.py's htmlcov and a gcovr or llvm-cov tree are the same thing to it. A path reaching outside the package refuses.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def package_coverage_reports(package: Package) -> list[tuple[str, str]]:
    """The coverage reports *package* declares: (label, path) each.

    The ``[docs]`` table's ``coverage`` list: a label and the
    package-relative path where the package's own tooling writes a
    static HTML tree. The toolchain never learns the producing tool;
    coverage.py's htmlcov and a gcovr or llvm-cov tree are the same
    thing to it. A path reaching outside the package refuses.
    """
    contract_path = package.directory / "workshop.toml"
    contract = read_contract(package.directory)
    table = contract.get("docs") or {}
    declared = table.get("coverage") if isinstance(table, dict) else None
    if declared is None:
        return []
    if not isinstance(declared, list):
        fail(f"{contract_path}: [docs] coverage must be a list")
    reports: list[tuple[str, str]] = []
    for entry in declared:
        if (
            isinstance(entry, dict)
            and isinstance(entry.get("label"), str)
            and entry["label"]
            and isinstance(entry.get("path"), str)
            and entry["path"]
        ):
            path = Path(entry["path"])
            if path.is_absolute() or ".." in path.parts:
                fail(
                    f"{contract_path}: [docs] coverage path {entry['path']!r}"
                    " must stay inside the package"
                )
            reports.append((entry["label"], entry["path"]))
            continue
        fail(
            f"{contract_path}: [docs] coverage entry {entry!r} is not a"
            ' { label = "...", path = "..." } table'
        )
    return reports

generate_coverage_pages

generate_coverage_pages(root: Path) -> list[str]

Copy declared coverage trees and write each coverage page.

One page per declaring package, one iframe per report, into the package's generated tree, which the mount merges. A declared tree that is missing renders its section saying so and the build stays green: on a machine that has not measured, the absence is stated rather than failing the site. On a push to main the page carries its iframe whether or not the tree exists yet: the gate job's docs.publish runs the deploy phase after the union and puts the trees into the built site (refresh_site_coverage), so a missing tree there is one the deploy phase will have drawn, or one its page states the absence of.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def generate_coverage_pages(root: Path) -> list[str]:
    """Copy declared coverage trees and write each coverage page.

    One page per declaring package, one iframe per report, into the
    package's generated tree, which the mount merges. A declared tree
    that is missing renders its section saying so and the build stays
    green: on a machine that has not measured, the absence is stated
    rather than failing the site. On a push to main the page carries
    its iframe whether or not the tree exists yet: the gate job's
    ``docs.publish`` runs the deploy phase after the union and puts the
    trees into the built site (`refresh_site_coverage`), so a missing
    tree there is one the deploy phase will have drawn, or one its page
    states the absence of.
    """
    from livery.workshop import ci_run

    run = ci_run()
    deferred = run is not None and run.event == "push"
    written: list[str] = []
    for package in discover_packages(root):
        reports = package_coverage_reports(package)
        if not reports:
            continue
        name = package.member
        mount = package.directory / "docs" / GENERATED_DIR
        mount.mkdir(parents=True, exist_ok=True)
        lines = ["# Coverage", ""]
        for label, path in reports:
            source = package.directory / path
            slug = _slug(label)
            lines += [f"## {label}", ""]
            present = (source / "index.html").is_file()
            if present:
                target = mount / "coverage" / slug
                shutil.rmtree(target, ignore_errors=True)
                shutil.copytree(source, target)
            if present or deferred:
                lines += [
                    f'<iframe src="../coverage/{slug}/index.html"'
                    f' title="{label}"'
                    ' style="width: 100%; height: 80vh; border: none;">'
                    "</iframe>",
                    "",
                ]
            else:
                lines += [
                    f"The declared report (`{path}`) was not produced in this build.",
                    "",
                ]
        mount.mkdir(parents=True, exist_ok=True)
        (mount / "coverage.md").write_text(
            "\n".join(lines).rstrip() + "\n", encoding="utf-8"
        )
        written.append(name)
    return written

refresh_site_coverage

refresh_site_coverage(root: Path) -> list[str]

Put each package's coverage trees into the built site; the packages refreshed.

The site publishes a package's section at packages/<member>/ and the trees its page frames under coverage/<slug>/ beside it, where the mount put them. docs.publish calls it after the deploy phase, so a tree a step of that phase drew after the build is copied over the one the build carried; a declared report with no tree gets a page stating the absence, so the section's iframe never points at nothing. Nothing is done without a built site.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def refresh_site_coverage(root: Path) -> list[str]:
    """Put each package's coverage trees into the built site; the packages refreshed.

    The site publishes a package's section at ``packages/<member>/``
    and the trees its page frames under ``coverage/<slug>/`` beside
    it, where the mount put them. ``docs.publish`` calls it after the
    deploy phase, so a tree a step of that phase drew after the build
    is copied over the one the build carried; a declared report with
    no tree gets a page stating the absence, so the section's iframe
    never points at nothing. Nothing is done without a built site.
    """
    site = root / "site"
    if not (site / "index.html").is_file():
        return []
    refreshed: list[str] = []
    for package in discover_packages(root):
        reports = package_coverage_reports(package)
        if not reports:
            continue
        for label, path in reports:
            source = package.directory / path
            target = site / "packages" / package.member / "coverage" / _slug(label)
            shutil.rmtree(target, ignore_errors=True)
            if (source / "index.html").is_file():
                shutil.copytree(source, target)
                continue
            target.mkdir(parents=True, exist_ok=True)
            (target / "index.html").write_text(
                f"<p>No measured data for {package.member} ({label}) in this"
                " run's record.</p>\n",
                encoding="utf-8",
            )
        refreshed.append(package.member)
    return refreshed

package_nav

package_nav(package: Package) -> list[object] | None

The package's authored nav tree, or None without a nav.toml.

The file's nav key mirrors the rendered config's shape: a list of one-key tables mapping a label to a page path (relative to the package's docs/ tree) or to a nested list. A placed machine block travels as a sentinel leaf, nav:<name>, where its markers sit. Anything else refuses naming the file and the entry.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def package_nav(package: Package) -> list[object] | None:
    """The package's authored nav tree, or None without a ``nav.toml``.

    The file's ``nav`` key mirrors the rendered config's shape: a
    list of one-key tables mapping a label to a page path (relative
    to the package's ``docs/`` tree) or to a nested list. A placed
    machine block travels as a sentinel leaf, `nav:<name>`, where its
    markers sit. Anything else refuses naming the file and the entry.
    """
    authored = authored_nav(package)
    return None if authored is None else authored[0]

authored_nav

authored_nav(package: Package) -> tuple[list[object], dict[str, list[object]]] | None

The authored tree with its placed blocks as sentinels, and each block's entries.

A marker pair names an emitted block or a generator's own; a marker without its twin, or a pair out of order, refuses naming the file and the block. The entries between a pair (the tasks block the task reference writes) come back keyed by the block's name, so the emitter renders them in the sentinel's place.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def authored_nav(
    package: Package,
) -> tuple[list[object], dict[str, list[object]]] | None:
    """The authored tree with its placed blocks as sentinels, and each block's entries.

    A marker pair names an emitted block or a generator's own; a
    marker without its twin, or a pair out of order, refuses naming
    the file and the block. The entries between a pair (the tasks
    block the task reference writes) come back keyed by the block's
    name, so the emitter renders them in the sentinel's place.
    """
    path = package.directory / "docs" / NAV_TOML
    if not path.is_file():
        return None
    generated = package.directory / "docs" / GENERATED_DIR
    text, blocks = _lift_blocks(path, path.read_text("utf-8"), generated)
    try:
        parsed = tomllib.loads(text)
    except tomllib.TOMLDecodeError as error:
        fail(f"{path} is not valid TOML: {error}")
    nav = parsed.get("nav")
    if not isinstance(nav, list):
        fail(f"{path} must carry a top-level `nav` list")
    _check_nav_shape(path, nav)
    return list(nav), blocks

check_package_nav

check_package_nav(package: Package, entries: list[object]) -> None

Refuse an authored nav that disagrees with the docs tree.

Both directions: an entry naming a missing page, and an authored page the nav does not carry. Entries under _generated/ are exempt from the missing check (a generator writes them at build time, and the strict site build owns them); generated pages are likewise not required in the nav. includes/ is exempt from the orphan check: its pages are snippet and glossary sources the extension set consumes (docs/includes/abbreviations.md is auto-appended site-wide), never standalone pages.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def check_package_nav(package: Package, entries: list[object]) -> None:
    """Refuse an authored nav that disagrees with the docs tree.

    Both directions: an entry naming a missing page, and an authored
    page the nav does not carry. Entries under ``_generated/`` are
    exempt from the missing check (a generator writes them at build
    time, and the strict site build owns them); generated pages are
    likewise not required in the nav. ``includes/`` is exempt from the
    orphan check: its pages are snippet and glossary sources the
    extension set consumes (``docs/includes/abbreviations.md`` is
    auto-appended site-wide), never standalone pages.
    """
    docs = package.directory / "docs"
    leaves = _nav_leaves(entries)
    authored = {
        page for page in _pages(docs) if not page.startswith((GENERATED, "includes/"))
    }
    nav_path = docs / NAV_TOML
    missing = [
        leaf
        for leaf in leaves
        if not leaf.startswith((GENERATED, SENTINEL)) and leaf not in authored
    ]
    if missing:
        fail(f"{nav_path} names pages that do not exist: " + ", ".join(sorted(missing)))
    orphans = sorted(authored - set(leaves))
    if orphans:
        fail(
            f"{nav_path} does not carry these authored pages: "
            + ", ".join(orphans)
            + ". Add them to the nav, or delete them."
        )

abbreviation_files

abbreviation_files(root: Path) -> list[str]

Every package's committed glossary, for the site-wide append.

docs/includes/abbreviations.md per package, as paths relative to root. Tooltips are site-wide, so a term two packages define differently refuses naming the term and both packages; the same definition twice is allowed.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def abbreviation_files(root: Path) -> list[str]:
    """Every package's committed glossary, for the site-wide append.

    ``docs/includes/abbreviations.md`` per package, as paths relative
    to *root*. Tooltips are site-wide, so a term two packages define
    differently refuses naming the term and both packages; the same
    definition twice is allowed.
    """
    import re

    definitions: dict[str, tuple[str, str]] = {}
    files: list[str] = []
    for package in discover_packages(root):
        glossary = package.directory / "docs" / "includes" / "abbreviations.md"
        if not glossary.is_file():
            continue
        files.append(glossary.relative_to(root).as_posix())
        for line in glossary.read_text("utf-8").splitlines():
            match = re.match(r"\*\[(.+?)\]:\s*(.+)", line)
            if match is None:
                continue
            term, definition = match.group(1), match.group(2).strip()
            known = definitions.get(term)
            if known is not None and known[0] != definition:
                fail(
                    f"abbreviation {term!r} is defined differently by"
                    f" {known[1]} and {package.name}; tooltips are"
                    " site-wide, so one definition must win: agree on"
                    " one, or rename the terms apart"
                )
            definitions.setdefault(term, (definition, package.name))
    return files

package_docs_extras

package_docs_extras(package: Package) -> tuple[list[str], list[object]]

The css and javascript a package's [docs] table declares.

extra-css entries are paths relative to the package's docs/ tree; extra-javascript entries are the same, or tables carrying path with type, defer, and async. Anything else refuses naming the file and the entry.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def package_docs_extras(package: Package) -> tuple[list[str], list[object]]:
    """The css and javascript a package's ``[docs]`` table declares.

    ``extra-css`` entries are paths relative to the package's
    ``docs/`` tree; ``extra-javascript`` entries are the same, or
    tables carrying ``path`` with ``type``, ``defer``, and ``async``.
    Anything else refuses naming the file and the entry.
    """
    contract_path = package.directory / "workshop.toml"
    contract = read_contract(package.directory)
    table = contract.get("docs") or {}
    if not isinstance(table, dict):
        return ([], [])
    css_declared = table.get("extra-css", [])
    js_declared = table.get("extra-javascript", [])
    if not isinstance(css_declared, list) or not all(
        isinstance(entry, str) for entry in css_declared
    ):
        fail(f"{contract_path}: [docs] extra-css must be a list of paths")
    allowed = {"path", "type", "defer", "async"}
    for entry in js_declared if isinstance(js_declared, list) else ():
        if isinstance(entry, str):
            continue
        if (
            isinstance(entry, dict)
            and isinstance(entry.get("path"), str)
            and set(entry) <= allowed
        ):
            continue
        fail(
            f"{contract_path}: [docs] extra-javascript entry {entry!r} is"
            " not a path or a { path, type, defer, async } table"
        )
    if not isinstance(js_declared, list):
        fail(f"{contract_path}: [docs] extra-javascript must be a list")
    return (list(css_declared), list(js_declared))

stage_extension_assets

stage_extension_assets(root: Path) -> list[str]

Copy every extension's site assets under docs/_extensions/; those staged.

Rebuilt whole: a file an extension no longer ships leaves no stale copy, and an extension that left the workspace loses its directory.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def stage_extension_assets(root: Path) -> list[str]:
    """Copy every extension's site assets under ``docs/_extensions/``; those staged.

    Rebuilt whole: a file an extension no longer ships leaves no stale
    copy, and an extension that left the workspace loses its directory.
    """
    base = root / "docs" / EXTENSION_ASSETS
    shutil.rmtree(base, ignore_errors=True)
    staged: list[str] = []
    for extension, assets in extension_assets(root):
        shutil.copytree(assets, base / extension / "assets")
        staged.append(extension)
    return staged

theme_values

theme_values(root: Path) -> dict[str, object]

The theme block's values the listed extensions answer, by key.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def theme_values(root: Path) -> dict[str, object]:
    """The theme block's values the listed extensions answer, by key."""
    return dict(answer(root, THEME))

zensical_config

zensical_config(root: Path) -> str

The assembled zensical.toml body, header excluded.

Site identity comes from the [docs] table (title defaults to the root project's name); the nav carries the root docs/ pages, the release view and every package's section at its mount path; the theme, extension set, and asset lists follow, then the tables the listed extensions answer docs.config with, in list order, over every package. The whole file is the build's: hand customisation goes through the contract and the packages' nav.toml files.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def zensical_config(root: Path) -> str:
    """The assembled ``zensical.toml`` body, header excluded.

    Site identity comes from the ``[docs]`` table (title defaults to
    the root project's name); the nav carries the root ``docs/``
    pages, the release view and every package's section at its mount
    path; the theme, extension set, and asset lists follow, then the
    tables the listed extensions answer ``docs.config`` with, in list
    order, over every package. The whole file is the build's: hand
    customisation goes through the contract and the packages'
    ``nav.toml`` files.
    """
    table = docs_table(root)
    title = str(table.get("title", "")) or project_name(root)
    site_url = str(table.get("site-url", ""))
    description = str(table.get("description", ""))
    lines = ["[project]", f'site_name = "{title}"']
    if site_url:
        lines.append(f'site_url = "{site_url}"')
    if description:
        lines.append(f'site_description = "{description}"')
    lines.append("nav = [")
    lines.append(f"    {NAV_BEGIN}")
    for page in _root_pages(root):
        label = "Home" if page == "index.md" else _label(page)
        lines.append(f'    {{ "{label}" = "{page}" }},')
    if any(
        (package.directory / "CHANGELOG.md").is_file()
        for package in discover_packages(root)
    ):
        # Committed state only: the tags are absent in a shallow CI
        # clone, and a nav derived from them would make the same
        # contract render differently per checkout. The landing page
        # links its own year archives at build time instead.
        lines.append('    { "Releases" = "releases/index.md" },')
    lines += development_nav_lines(root)
    packages = discover_packages(root)
    lines += packages_nav_lines(packages)
    lines.append(f"    {NAV_END}")
    lines.append("]")
    lines += _extra_asset_lines(root)
    lines += _theme_lines(theme_values(root))
    lines += _extension_block(root)
    return joined("\n".join(lines) + "\n", Scope(root, packages))

packages_nav_lines

packages_nav_lines(packages: tuple[Package, ...]) -> list[str]

The nav's one Packages entry: the landing page, then the tree.

Empty for a workspace without packages.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def packages_nav_lines(packages: tuple[Package, ...]) -> list[str]:
    """The nav's one Packages entry: the landing page, then the tree.

    Empty for a workspace without packages.
    """
    if not packages:
        return []
    tree = package_tree(packages)
    entries = [
        line for child in tree.ordered() for line in _place_lines(child, "        ")
    ]
    return [
        '    { "Packages" = [',
        f'        {{ "Index" = "packages/{LANDING}" }},',
        *entries,
        "    ] },",
    ]

changelog_page

changelog_page(root: Path, package: Package) -> str | None

The package's changelog page; None without a changelog.

The committed file, with what is unreleased prepended in memory (the file on disk never changes). When git-cliff cannot answer, an offline checkout or a package without its config, the page is the file alone and the reason is printed, never swallowed into a broken page.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def changelog_page(root: Path, package: Package) -> str | None:
    """The package's changelog page; None without a changelog.

    The committed file, with what is unreleased prepended in memory
    (the file on disk never changes). When git-cliff cannot answer,
    an offline checkout or a package without its config, the page is
    the file alone and the reason is printed, never swallowed into a
    broken page.
    """
    changelog = package.directory / "CHANGELOG.md"
    if not changelog.is_file():
        return None
    text = changelog.read_text("utf-8")
    from livery.workshop import release_notes

    notes = release_notes(root)
    try:
        unreleased = notes.entry(root, package) if notes is not None else ""
    except BaseException as error:
        print(f"  {package.name}: unreleased section skipped: {error}")
        unreleased = ""
    if unreleased:
        text = _insert_after_title(text, unreleased)
    return text

generate_changelog_pages

generate_changelog_pages(root: Path) -> list[str]

Write each package's changelog page into its generated tree; the names.

The mount merges the tree, so the page lands where the nav points.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def generate_changelog_pages(root: Path) -> list[str]:
    """Write each package's changelog page into its generated tree; the names.

    The mount merges the tree, so the page lands where the nav points.
    """
    generated: list[str] = []
    for package in discover_packages(root):
        page = changelog_page(root, package)
        if page is None:
            continue
        target = package.directory / "docs" / GENERATED_DIR / "changelog.md"
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(page, encoding="utf-8")
        generated.append(package.member)
    return generated

release_years

release_years(root: Path) -> list[str]

The archive years the view paginates into, newest first.

Every year with a release except the newest, which lives on the landing page.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def release_years(root: Path) -> list[str]:
    """The archive years the view paginates into, newest first.

    Every year with a release except the newest, which lives on the
    landing page.
    """
    years = sorted({tag[0][:4] for tag in _receipt_tags(root)}, reverse=True)
    return years[1:]

generate_release_pages

generate_release_pages(root: Path) -> list[str]

Write the site-wide release view; the page paths written.

Derived from the receipt tags joined with the changelog entries they point at, newest first across members. Paginated: the newest year's releases on the landing page, each earlier year on its own archive page linked from it.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def generate_release_pages(root: Path) -> list[str]:
    """Write the site-wide release view; the page paths written.

    Derived from the receipt tags joined with the changelog entries
    they point at, newest first across members. Paginated: the
    newest year's releases on the landing page, each earlier year on
    its own archive page linked from it.
    """
    base = root / RELEASES
    shutil.rmtree(base, ignore_errors=True)
    tags = _receipt_tags(root)
    if not tags:
        if any(
            (package.directory / "CHANGELOG.md").is_file()
            for package in discover_packages(root)
        ):
            # The nav points here whenever a changelog exists, so the
            # page must too: a checkout without the tags (a shallow CI
            # clone) states that plainly instead of serving a 404.
            base.mkdir(parents=True)
            (base / "index.md").write_text(
                "# Releases\n\nNo release tags in this checkout.\n",
                encoding="utf-8",
            )
            return ["index.md"]
        return []
    base.mkdir(parents=True)
    years = sorted({tag[0][:4] for tag in tags}, reverse=True)
    newest, archived = years[0], years[1:]
    written: list[str] = []

    def _page(title: str, year: str, links: list[str]) -> str:
        blocks = [f"# {title}", ""]
        blocks += [_release_block(root, tag) for tag in tags if tag[0][:4] == year]
        blocks += links
        return "\n".join(blocks).rstrip("\n") + "\n"

    links = (
        ["", "Older releases: " + ", ".join(f"[{y}]({y}.md)" for y in archived), ""]
        if archived
        else []
    )
    (base / "index.md").write_text(_page("Releases", newest, links), encoding="utf-8")
    written.append("index.md")
    for year in archived:
        (base / f"{year}.md").write_text(
            _page(f"Releases in {year}", year, []), encoding="utf-8"
        )
        written.append(f"{year}.md")
    return written

section_digest

section_digest(docs: Path) -> str

A digest of a package's docs tree: every file's path and bytes.

Content, never mtimes: a generator rewrites its pages on every run, and an unchanged page must not move the digest. The coverage report tree is left out, since a measured report is stamped with its time and would move the digest on every build.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def section_digest(docs: Path) -> str:
    """A digest of a package's docs tree: every file's path and bytes.

    Content, never mtimes: a generator rewrites its pages on every
    run, and an unchanged page must not move the digest. The coverage
    report tree is left out, since a measured report is stamped with
    its time and would move the digest on every build.
    """
    import hashlib

    digest = hashlib.sha256()
    for path in sorted(p for p in docs.rglob("*") if p.is_file()):
        relative = path.relative_to(docs).as_posix()
        if relative.startswith(COVERAGE_TREE):
            continue
        digest.update(relative.encode() + b"\0")
        digest.update(path.read_bytes())
        digest.update(b"\n")
    return digest.hexdigest()

mount_package_docs

mount_package_docs(root: Path, *, full: bool = False) -> list[str]

Mount every package's docs/ into the site tree; the names copied.

A package's mount is rebuilt whole when its docs tree's digest moved since the last mount, or with full; an unchanged section is left in place with its coverage report refreshed, and a package that left the workspace loses its mount. nav.toml stays behind: it configures the nav and is not site content. The package's generated tree merges into the mount's root and every link into it in a mounted page loses the prefix, so _generated names a directory on disk and never a published path. A generated page that an authored page already holds the path of refuses, naming both.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def mount_package_docs(root: Path, *, full: bool = False) -> list[str]:
    """Mount every package's ``docs/`` into the site tree; the names copied.

    A package's mount is rebuilt whole when its docs tree's digest
    moved since the last mount, or with *full*; an unchanged section
    is left in place with its coverage report refreshed, and a package
    that left the workspace loses its mount. ``nav.toml`` stays behind:
    it configures the nav and is not site content. The package's
    generated tree merges into the mount's root and every link into it
    in a mounted page loses the prefix, so ``_generated`` names a
    directory on disk and never a published path. A generated page
    that an authored page already holds the path of refuses, naming
    both.
    """
    base = root / MOUNT
    stamps = root / BUILD_DIR
    stamps.mkdir(exist_ok=True)
    if full:
        shutil.rmtree(base, ignore_errors=True)
    base.mkdir(parents=True, exist_ok=True)
    present = {package.member for package in discover_packages(root)}
    for stale in _stale_mounts(base, present):
        shutil.rmtree(base / stale, ignore_errors=True)
        (stamps / f"{stale}.digest").unlink(missing_ok=True)
    mounted: list[str] = []
    for package in discover_packages(root):
        docs = package.directory / "docs"
        name = package.member
        target = base / name
        stamp = stamps / f"{name}.digest"
        if not docs.is_dir():
            shutil.rmtree(target, ignore_errors=True)
            stamp.unlink(missing_ok=True)
            continue
        digest = section_digest(docs)
        if (
            not full
            and target.is_dir()
            and stamp.is_file()
            and stamp.read_text(encoding="utf-8") == digest
        ):
            _refresh_coverage(docs, target)
            continue
        shutil.rmtree(target, ignore_errors=True)
        shutil.copytree(
            docs,
            target,
            ignore=lambda directory, names, docs=docs: (
                [NAV_TOML, GENERATED_DIR]
                if Path(directory) == docs
                # The package's setup around its examples is not site content.
                else ["conftest.py"]
                if Path(directory) == docs / "examples"
                else []
            ),
        )
        _merge_generated(docs / GENERATED_DIR, target, package.path)
        _strip_generated_links(target)
        # A member in a group directory keeps its stamp in the group's.
        stamp.parent.mkdir(parents=True, exist_ok=True)
        stamp.write_text(digest, encoding="utf-8")
        mounted.append(name)
    return mounted

published_url

published_url(page: str) -> str

The URL path a markdown page publishes at with directory URLs.

a/b.md and a/b/index.md are both a/b/; the root index.md is the empty path.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def published_url(page: str) -> str:
    """The URL path a markdown page publishes at with directory URLs.

    ``a/b.md`` and ``a/b/index.md`` are both ``a/b/``; the root
    ``index.md`` is the empty path.
    """
    stem = page.removesuffix(".md")
    if stem == "index":
        return ""
    if stem.endswith("/index"):
        return stem.removesuffix("index")
    return stem + "/"

named_package

named_package(root: Path, name: str) -> Package

The package whose directory is name; refuses naming the known.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def named_package(root: Path, name: str) -> Package:
    """The package whose directory is *name*; refuses naming the known."""
    packages = discover_packages(root)
    for package in packages:
        if package.member == name:
            return package
    known = ", ".join(sorted(p.member for p in packages)) or "none"
    fail(f"no package {name!r} in this workspace (known: {known})")

scoped_config

scoped_config(root: Path, package: Package) -> str

The scoped preview's config body: chrome plus one section.

The workspace's site name and authored root pages, then only package's section. No site URL and no release view: the preview is never published, and the release view is site-wide. The tables the listed extensions answer docs.config with follow for the one package, read from the preview's directory, with the published site's address when the contract declares one, so a reference to another package resolves on the published site.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def scoped_config(root: Path, package: Package) -> str:
    """The scoped preview's config body: chrome plus one section.

    The workspace's site name and authored root pages, then only
    *package*'s section. No site URL and no release view: the
    preview is never published, and the release view is site-wide.
    The tables the listed extensions answer ``docs.config`` with
    follow for the one package, read from the preview's directory,
    with the published site's address when the contract declares
    one, so a reference to another package resolves on the
    published site.
    """
    table = docs_table(root)
    title = str(table.get("title", "")) or project_name(root)
    lines = ["[project]", f'site_name = "{title}"', "nav = ["]
    for page in _root_pages(root):
        label = "Home" if page == "index.md" else _label(page)
        lines.append(f'    {{ "{label}" = "{page}" }},')
    lines += _package_section(package)
    lines.append("]")
    lines += _theme_lines(theme_values(root))
    lines += _extension_block(root, relative_to=PREVIEW_ROOT)
    scope = Scope(
        root,
        (package,),
        anchor=PREVIEW_ROOT + "/",
        published=str(table.get("site-url", "")),
    )
    return joined("\n".join(lines) + "\n", scope)

materialise_preview

materialise_preview(root: Path, package: Package) -> Path

Materialise one package's preview tree; the scoped config's path.

Rebuilt whole under .docs-preview/<name>/: the authored root pages, the package's freshly generated mount, and the scoped config beside them. The rendered root config is never touched. Callers run the mount and generation passes first, so the copied trees are current.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def materialise_preview(root: Path, package: Package) -> Path:
    """Materialise one package's preview tree; the scoped config's path.

    Rebuilt whole under ``.docs-preview/<name>/``: the authored root
    pages, the package's freshly generated mount, and the scoped
    config beside them. The rendered root config is never
    touched. Callers run the mount and generation passes first, so
    the copied trees are current.
    """
    from livery.workshop import generated_header

    name = package.member
    base = root / PREVIEW / name
    shutil.rmtree(base, ignore_errors=True)
    docs = base / "docs"
    shutil.copytree(
        root / "docs",
        docs,
        ignore=lambda directory, names: (
            list(SITE_TREES) if Path(directory) == root / "docs" else []
        ),
    )
    mount = root / MOUNT / name
    if mount.is_dir():
        shutil.copytree(mount, docs / "packages" / name)
    overrides = root / "overrides"
    if overrides.is_dir():
        shutil.copytree(overrides, base / "overrides")
    config = base / "zensical.toml"
    config.write_text(
        generated_header("#") + scoped_config(root, package), encoding="utf-8"
    )
    return config

run_site_phase

run_site_phase(root: Path, phase: str) -> None

Run the steps registered for phase over the workspace at root.

Through the walk every phase runs through, its steps side by side: the docs extension's own and those a listed extension adds in its [for.docs] table, each registered while it applies. A failing step turns the verb red once every step ran, the step named in the walk's lines. A phase with no registered step runs nothing.

Before the steps run, what a step that stopped running wrote outside the generated trees goes, wherever it wrote: each step declares those paths under outputs, and in the docs phase each generator a package lists under [docs] generators declares its own (generator_outputs).

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def run_site_phase(root: Path, phase: str) -> None:
    """Run the steps registered for *phase* over the workspace at *root*.

    Through the walk every phase runs through, its steps side by side:
    the docs extension's own and those a listed extension adds in its
    ``[for.docs]`` table, each registered while it applies. A failing
    step turns the verb red once every step ran, the step named in the
    walk's lines. A phase with no registered step runs nothing.

    Before the steps run, what a step that stopped running wrote
    outside the generated trees goes, wherever it wrote: each step
    declares those paths under ``outputs``, and in the docs phase each
    generator a package lists under ``[docs] generators`` declares its
    own (`generator_outputs`).
    """
    outputs = generator_outputs(root) if phase == DOCS_PHASE else ()
    run_phase(root, phase, outputs=outputs)

emit_section_navs

emit_section_navs(root: Path) -> list[str]

Emit each package's complete section nav into its generated tree; the names.

The section as the assembled config carries it: the authored tree with every block filled, paths as they publish. One file per package, docs/_generated/nav.toml, gitignored, so the section is whole on disk beside its pages.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def emit_section_navs(root: Path) -> list[str]:
    """Emit each package's complete section nav into its generated tree; the names.

    The section as the assembled config carries it: the authored tree
    with every block filled, paths as they publish. One file per
    package, ``docs/_generated/nav.toml``, gitignored, so the section
    is whole on disk beside its pages.
    """
    emitted: list[str] = []
    for package in discover_packages(root):
        section = _package_section(package, indent="")
        if not section:
            continue
        generated = package.directory / "docs" / GENERATED_DIR
        generated.mkdir(parents=True, exist_ok=True)
        (generated / NAV_TOML).write_text(
            "# This section as the site assembles it, emitted by the build;"
            " the authored\n# nav.toml beside it is the source.\nnav = [\n"
            + "\n".join(section)
            + "\n]\n",
            encoding="utf-8",
        )
        emitted.append(package.member)
    return emitted

write_site_config

write_site_config(root: Path) -> Path

Assemble the config zensical reads and write it to the root; the path.

Gitignored and rebuilt on every docs verb: the site's identity from the contract, the root pages, one section per package, the theme and the extension set. The header says so, since the file reads like a rendered one.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def write_site_config(root: Path) -> Path:
    """Assemble the config zensical reads and write it to the root; the path.

    Gitignored and rebuilt on every docs verb: the site's identity from
    the contract, the root pages, one section per package, the theme
    and the extension set. The header says so, since the file reads
    like a rendered one.
    """
    from livery.workshop import generated_header

    header = generated_header(
        "#",
        (
            "Assembled by the docs build from workshop.toml and every package's",
            "section; gitignored and rewritten on every docs verb, never edited.",
        ),
    )
    path = root / SITE_CONFIG
    path.write_text(header + zensical_config(root), encoding="utf-8")
    return path

clear_generated

clear_generated(root: Path) -> None

Remove the generated trees an earlier build left: the root's and each package's.

Each is a docs/_generated/ directory, which the docs phase's steps and the site's own passes write again whole. Run before the phase, so a step that no longer runs, its extension unlisted or the step turned off, leaves no page and no nav block behind. What a step writes outside a generated tree stays: a coverage report's own directory, and the site trees under the root's docs/.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def clear_generated(root: Path) -> None:
    """Remove the generated trees an earlier build left: the root's and each package's.

    Each is a ``docs/_generated/`` directory, which the docs phase's
    steps and the site's own passes write again whole. Run before the
    phase, so a step that no longer runs, its extension unlisted or
    the step turned off, leaves no page and no nav block behind. What
    a step writes outside a generated tree stays: a coverage report's
    own directory, and the site trees under the root's ``docs/``.
    """
    trees = [root / "docs" / GENERATED_DIR]
    trees += [
        package.directory / "docs" / GENERATED_DIR
        for package in discover_packages(root)
    ]
    for tree in trees:
        if tree.is_dir():
            shutil.rmtree(tree)

docs_build

docs_build(package: Annotated[str, doc("build a scoped preview of this package's section only")] = '', full: Annotated[bool, doc("rebuild every package's mount whole")] = False) -> None

Mount every package's docs, assemble the config, and build the site, strict.

Strict is the point: a broken link or an orphan page fails here, on the machine, before CI says the same thing. --package builds a scoped preview of one section instead, into the gitignored .docs-preview/ directory; the preview is not strict, because chrome pages may link into sections it does not carry, and the workspace build owns strictness. A package whose docs did not move keeps its mount; --full rebuilds them all.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
@docs_group.task(name="build")
def docs_build(
    package: Annotated[
        str, doc("build a scoped preview of this package's section only")
    ] = "",
    full: Annotated[bool, doc("rebuild every package's mount whole")] = False,
) -> None:
    """Mount every package's docs, assemble the config, and build the site, strict.

    Strict is the point: a broken link or an orphan page fails here,
    on the machine, before CI says the same thing. ``--package``
    builds a scoped preview of one section instead, into the
    gitignored ``.docs-preview/`` directory; the preview is not
    strict, because chrome pages may link into sections it does not
    carry, and the workspace build owns strictness. A package whose
    docs did not move keeps its mount; ``--full`` rebuilds them all.
    """
    root = _root()
    require_sources(root)
    _generate_all(root, full=full)
    if package:
        config = materialise_preview(root, named_package(root, package))
        result = tools.zensical.opts(cwd=config.parent, nofail=True).build(
            clean=True, config_file=str(config)
        )
        if result.code != 0:
            fail(
                f"zensical build exited {result.code}:\n{result.stdout}{result.stderr}"
            )
        print(f"  preview built at {config.parent / 'site'} (never published)")
        return
    developed = generate_development_pages(root)
    if developed:
        print(f"  development pages: {', '.join(developed)}")
    releases = generate_release_pages(root)
    if releases:
        print(f"  release view: {', '.join(releases)}")
    from livery.workshop import ci_run

    print(source_summary(root))
    result = tools.zensical.opts(cwd=root, nofail=True).build(clean=True, strict=True)
    if result.code != 0:
        fail(f"zensical build exited {result.code}:\n{result.stdout}{result.stderr}")
    in_ci = ci_run() is not None
    for line in generator_lines(result.stdout, result.stderr, in_ci=in_ci):
        print(line)
    from livery.extensions.docs._llms import write_llms_files

    written = write_llms_files(root)
    print(f"  agent files: {', '.join(written)}")
    require_site(root)
    print(f"  site built at {root / 'site'}")

require_sources

require_sources(root: Path) -> None

Refuse before the build when the site's sources are not in the checkout.

The generator has exited 0 in a fraction of its usual time with nothing on disk. The first thing to rule out is a checkout without the docs tree or the contract, so their absence is named here, before the generator runs, instead of surfacing as an empty site after it.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def require_sources(root: Path) -> None:
    """Refuse before the build when the site's sources are not in the checkout.

    The generator has exited 0 in a fraction of its usual time with
    nothing on disk. The first thing to rule out is a checkout
    without the docs tree or the contract, so their absence is named
    here, before the generator runs, instead of surfacing as an
    empty site after it.
    """
    missing = [name for name in ("docs", "workshop.toml") if not (root / name).exists()]
    if missing:
        fail(
            f"no site sources at {root}: {', '.join(missing)} missing; the"
            " build reads the docs tree and assembles its config from the contract"
        )

source_summary

source_summary(root: Path) -> str

One line on what the build reads: the pages under docs/.

Printed before every workspace build, so a run that produced no site says what its checkout held.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def source_summary(root: Path) -> str:
    """One line on what the build reads: the pages under ``docs/``.

    Printed before every workspace build, so a run that produced no
    site says what its checkout held.
    """
    pages = sum(1 for _ in (root / "docs").rglob("*.md"))
    return f"  site sources: {pages} page(s) under docs/, the config assembled"

generator_lines

generator_lines(stdout: str, stderr: str, *, in_ci: bool) -> list[str]

The generator's own output, indented, for a run in CI; nothing otherwise.

A local build stays quiet on success. In CI the lines are the evidence a build that left no site leaves behind, so they are printed whether or not the build succeeded.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def generator_lines(stdout: str, stderr: str, *, in_ci: bool) -> list[str]:
    """The generator's own output, indented, for a run in CI; nothing otherwise.

    A local build stays quiet on success. In CI the lines are the
    evidence a build that left no site leaves behind, so they are
    printed whether or not the build succeeded.
    """
    if not in_ci:
        return []
    text = (stdout + stderr).strip()
    return [f"    {line}" for line in text.splitlines()] if text else []

require_site

require_site(root: Path) -> None

Refuse when the build left no site to publish.

The site generator has exited 0 in a fraction of its usual time with nothing on disk, and the publish that followed was the one to fail; the build is the one that knows, so it says so.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def require_site(root: Path) -> None:
    """Refuse when the build left no site to publish.

    The site generator has exited 0 in a fraction of its usual time
    with nothing on disk, and the publish that followed was the one
    to fail; the build is the one that knows, so it says so.
    """
    import livery.footman as footman

    index = root / "site" / "index.html"
    if not index.is_file():
        fail(
            f"the site build exited 0 but left no {index.as_posix()}: nothing"
            " to publish;"
            f" run `{footman.prog()} docs.build` again"
        )

docs_publish

docs_publish() -> None

Run the deploy phase on the built site, then publish it through the seam.

The deploy phase's steps run first, the ones the listed extensions add in their [for.docs] tables, each drawing a page from what the merge left behind; a failing step stops the publish, naming the step. Each declared coverage report's tree then goes into the site (refresh_site_coverage). Then the contract's seam: pages is the forge workflow's own act and skips here; container pushes the site image to the forge registry; ssh tars the site to the configured host, skipping when unconfigured; none skips by declaration.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
@docs_group.task(name="publish")
def docs_publish() -> None:
    """Run the deploy phase on the built site, then publish it through the seam.

    The deploy phase's steps run first, the ones the listed extensions
    add in their ``[for.docs]`` tables, each drawing a page from what
    the merge left behind; a failing step stops the publish, naming the
    step. Each declared coverage report's tree then goes into the site
    (`refresh_site_coverage`). Then the contract's seam: ``pages`` is
    the forge workflow's own act and skips here; ``container`` pushes
    the site image to the forge registry; ``ssh`` tars the site to the
    configured host, skipping when unconfigured; ``none`` skips by
    declaration.
    """
    root = _root()
    if not (root / "site" / "index.html").is_file():
        fail(f"no built site at {root / 'site'}: run `docs.build` first")
    run_site_phase(root, DEPLOY_PHASE)
    refreshed = refresh_site_coverage(root)
    if refreshed:
        print(f"  site refreshed for {', '.join(refreshed)}")
    seam = publish_seam(root)
    if seam == "container":
        _publish_container(root)
    elif seam == "ssh":
        _publish_ssh(root)
    elif seam == "pages":
        print("  pages seam: the forge's own workflow deploys; nothing to do here")
    else:
        print("  publish seam is none: skipping by declaration")

docs_serve

docs_serve(package: Annotated[str, doc("serve a scoped preview of this package's section only")] = '') -> None

Mount every package's docs and serve the site live.

--package serves the scoped preview instead, from the gitignored .docs-preview/ directory. Generated pages are copied at materialisation, so an edit to a package page needs a re-run to appear in the preview.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
@docs_group.task(name="serve", infinite=True)
def docs_serve(
    package: Annotated[
        str, doc("serve a scoped preview of this package's section only")
    ] = "",
) -> None:
    """Mount every package's docs and serve the site live.

    ``--package`` serves the scoped preview instead, from the
    gitignored ``.docs-preview/`` directory. Generated pages are
    copied at materialisation, so an edit to a package page needs a
    re-run to appear in the preview.
    """
    root = _root()
    _generate_all(root)
    if package:
        config = materialise_preview(root, named_package(root, package))
        tools.zensical.opts(cwd=config.parent).serve(config_file=str(config))
        return
    generate_release_pages(root)
    tools.zensical.opts(cwd=root).serve()

section_title

section_title(section: str) -> str

The page title of a prose section: its name, capitalised.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def section_title(section: str) -> str:
    """The page title of a prose section: its name, capitalised."""
    return section.replace("-", " ").capitalize()

development_content

development_content(root: Path) -> dict[str, list[str]]

Each section's markdown for a human reader, in section order, empty left out.

The pages and the nav both read this, so the nav entry never waits on a page a previous build wrote.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def development_content(root: Path) -> dict[str, list[str]]:
    """Each section's markdown for a human reader, in section order, empty left out.

    The pages and the nav both read this, so the nav entry never waits
    on a page a previous build wrote.
    """
    # The guidance comes in section order, so the sections keep it.
    by_section: dict[str, list[str]] = {}
    for prose in guidance(root, HUMAN):
        text = prose.text(root, HUMAN).strip()
        if text:
            by_section.setdefault(prose.section, []).append(text)
    return by_section

generate_development_pages

generate_development_pages(root: Path) -> list[str]

Write the development section, one page per prose section; the pages written.

A section with no fragment for a human reader gets no page; a page carries each fragment's markdown in the order livery.workshop.guidance gives, headings demoted under the page's title. The index lists the pages. Rebuilt whole.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def generate_development_pages(root: Path) -> list[str]:
    """Write the development section, one page per prose section; the pages written.

    A section with no fragment for a human reader gets no page; a
    page carries each fragment's markdown in the order
    [livery.workshop.guidance][] gives, headings demoted under
    the page's title. The index lists the pages. Rebuilt whole.
    """
    base = root / DEVELOPMENT
    shutil.rmtree(base, ignore_errors=True)
    content = development_content(root)
    if not content:
        return []
    base.mkdir(parents=True)
    written: list[str] = []
    for section, texts in content.items():
        blocks = [f"# {section_title(section)}", ""]
        for text in texts:
            blocks += [_demoted(text), ""]
        page = base / f"{section}.md"
        page.write_text("\n".join(blocks).rstrip("\n") + "\n", encoding="utf-8")
        written.append(f"{section}.md")
    index = [
        "# Development",
        "",
        "How this workspace is developed, one page per section:",
        "",
    ]
    index += [f"- [{section_title(page[:-3])}]({page})" for page in written]
    (base / "index.md").write_text("\n".join(index) + "\n", encoding="utf-8")
    return ["index.md", *written]

development_nav_lines

development_nav_lines(root: Path) -> list[str]

The nav entry for the development section, empty without a section to show.

Source code in packages/extensions/docs/src/livery/extensions/docs/_site.py
def development_nav_lines(root: Path) -> list[str]:
    """The nav entry for the development section, empty without a section to show."""
    content = development_content(root)
    if not content:
        return []
    lines = [
        '    { "Development" = [',
        '        { "Overview" = "development/index.md" },',
    ]
    lines += [
        f'        {{ "{section_title(section)}" = "development/{section}.md" }},'
        for section in content
    ]
    lines.append("    ] },")
    return lines