Documentation maintenance
docs/ is the maintained documentation source. zensical.toml controls the site.
The separate wiki is retained for historical reference; do not maintain parallel
copies. The migration record
accounts for sources, exclusions, compatibility changes, and verification.
Setup
Use the repository's existing .venv; create it only if absent:
# Only when .venv does not already exist:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-docs.txt
.venv/bin/python -m pip check
Python 3.14 is used in CI and was used for migration validation. Installing the documentation requirements does not replace the application environment.
Preview and build
.venv/bin/zensical serve -f zensical.toml
.venv/bin/zensical build -f zensical.toml --clean --strict
.venv/bin/python scripts/check_docs.py
The preview at http://localhost:8000 is local only. Production is configured for
https://chris-day.github.io/uml2semantics-python/, inherited from MkDocs and
confirmed reachable during migration. Existing .html paths are retained.
site/ and caches are generated, ignored files.
Browser checks
.venv/bin/python -m pip install -r requirements-docs-browser.txt
.venv/bin/python -m playwright install chromium
.venv/bin/python scripts/check_docs_browser.py
The browser check serves the site under the production subpath, checks all Mermaid pages, search, favicon, repository links, and consent states, and records network requests and local storage. It requires a browser-capable environment.
Dependency updates
Update the Zensical pin in requirements-docs.in, install it in .venv, and
regenerate the transitive lock with:
.venv/bin/python -m pip install --upgrade -r requirements-docs.in
.venv/bin/python scripts/lock_docs.py
.venv/bin/python -m pip install -r requirements-docs.txt
Then run the clean strict build, link checks, browser checks, and application
tests before committing the lock. No separate mkdocs-llmstxt package is needed:
Zensical implements the configured export natively. llms.txt, llms-full.txt,
and page Markdown files are generated under site/ using the production base URL.
Deployment and rollback
The existing GitHub Pages workflow builds pull requests without deploying.
Pushes to main and manual dispatch build and deploy using the checkout's .venv
and pinned requirements. Pages must remain configured to use GitHub Actions.
No hosting settings or remote wiki are changed by the migration.
To roll back after a future deployment, revert the migration commit and rerun
the Pages workflow for that revision. Before committing, the legacy config is
available at documentation-migration/mkdocs.yml.legacy; restore it as
mkdocs.yml together with the previous workflow and docs from Git. The original
wiki remains available separately. Never deploy both configurations as competing
sources. GitHub Wiki URLs cannot be redirected by this Pages site.