Skip to content

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.