Building the documentation¶

These docs live in doc/ and are built with Zensical, configured by mkdocs.yml in the repository root - navigation, theme and Markdown extensions all come from that file.

Preview while you write¶

1
2
3
4

python3 -m venv .venv
source .venv/bin/activate
pip install zensical
zensical serve

The site shows up at http://localhost:8000 and reloads whenever you save a file. Later sessions only need source .venv/bin/activate before running zensical.

The supported XEP lists are generated, not written by hand - regenerate them with make xeplist, which runs the xep-tool against the compiled modules in _build/prod/lib, so it needs a built release. make docs-serve is make xeplist followed by zensical serve.

The GraphQL API reference pages will look empty: they are generated by the two npx spectaql commands in tools/build-docs.sh.

Before you push¶

1

zensical build --strict

Strict mode turns warnings into errors, most usefully links to pages and anchors that do not exist. CI runs the same command and the build takes a few seconds, so there is no reason to find out on CI instead. If the results look stale, add -c to drop the build cache.

make docs is the whole CI build - XEP lists, GraphQL pages and site - inside a Docker container, so it needs no Python or Node on your machine. When it fails, the mim_docs container is deliberately left running for you to docker exec -it mim_docs bash into.

Writing¶

Include another file with --8<-- "path/to/file.md", relative to doc/. Diagrams go in a ```mermaid fence. Content tabs, admonitions and highlighted code blocks with line numbers are available too.