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:
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
SENTINEL
module-attribute
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
PREVIEW
module-attribute
PREVIEW = '.docs-preview'
PREVIEW_ROOT
module-attribute
DOCS_PHASE
module-attribute
DEPLOY_PHASE
module-attribute
docs_group
module-attribute
docs_group = group('docs', help="The workspace's documentation site")
DEVELOPMENT
module-attribute
DEVELOPMENT = 'docs/development'
package_coverage_reports
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
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
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
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
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
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
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
|
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
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
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
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
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
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
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
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
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
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 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
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
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 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 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
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
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
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
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
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
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
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
|