Maintain the documentation site¶
The firmware site uses MkDocs Material, with the installer at /espurr/ and docs at
/espurr/docs/. The hardware link is /espurr-hw/: a same-origin path that also
works when both projects move to another domain. No second Pages deployment is used.
Build and preview locally¶
From the repository root, using Python 3.12 or newer:
python3 -m venv build/tools/docs-venv
build/tools/docs-venv/bin/python -m pip install -r site/requirements-docs.txt
build/tools/docs-venv/bin/python tools/docs.py check
build/tools/docs-venv/bin/python tools/docs.py build
This builds docs into build/docs/site. For a combined offline preview:
build/tools/docs-venv/bin/python tools/docs.py preview
python3 -m http.server 8000 --bind 127.0.0.1 --directory build/docs/preview
# Open http://127.0.0.1:8000/espurr/ or /espurr/docs/
The offline preview has an empty release catalogue and performs no GitHub release downloads. Use act smoke tests for fixture release assets and the actual workflow assembly. Never flash those descriptor-only smoke fixtures.
Source and publication policy¶
Edit the existing repository Markdown. The nav in mkdocs.yml
is the explicit source allowlist; tools/docs.py stages those files, strips the
leading docs/ and changes README.md to index.md in build output only.
App and component READMEs retain their source ownership and subtree.
Links between selected documents stay local. Links to other existing repository
files point to the exact source commit on GitHub. Local build/ evidence is labelled
as a local artifact rather than copied into the public site. Missing/escaping links
fail the build. tools/docs.py check checks links and anchors in every repository
Markdown file, including unpublished guides and records. Generated HTML links,
anchors and local assets are checked too.
Images need explicit publication support rather than implicitly copying a directory.
Only the history index is published. Dated acceptance records and old plans remain
in docs/history/, linked as source records outside normal site search. Store
submission and privacy drafts stay repository-only. Don't publish checkout paths,
private build logs or a draft privacy policy as finished user guidance.
The site describes the current source. It has no docs version selector; the installer's retained release list selects binaries only. A future versioned-docs policy needs to preserve both artifacts and their source provenance deliberately.
CI and Pages¶
Ordinary CI installs the pinned docs requirements, runs the documentation regression
checks and builds the site strictly. The existing Pages job first assembles the
installer and retained release assets, then adds MkDocs under build/site/docs.
Pages uses Ubuntu 24.04's Python 3.12 with an explicit docs virtualenv; it does not
activate that environment or change the runner's PATH.
It uploads one combined artifact, and the existing guarded deploy job consumes it.
Docs, app/component README, config and build-tool changes trigger the Pages build.
Local builds never deploy. The workflows retain their ACT guards around remote
publishing/configuration/deployment. See CI and releases.