Commands

On this page

The project deliberately exposes only a few commands.

Show the version#

python3 build.py --version

Build the documentation#

python3 build.py

The bundled manual/languages.json configures English at /en/ and a partial Polish example at /pl/. External --source directories may use the same manifest layout or a flat English tree. See language configuration.

Build for a forge project path:

python3 build.py --base-path /example-project/

Select a bundled theme:

python3 build.py --theme paper

Build an offline ZIP that opens without a server:

python3 build.py \
  --offline-archive artifacts/manual-site-offline.zip

Render Mermaid diagrams after installing the host Mermaid toolchain (Node.js 22.12+, npm-installed mmdc, and a working Puppeteer browser):

python3 build.py --mermaid

Rendering is opt-in; default builds show escaped, searchable code. For the recommended container toolchain, see optional Mermaid rendering. Use python3 build.py --help for all build options.

Run the tests#

python3 -m unittest discover -s tests -v

Run the optional real-renderer checks in the Mermaid builder container:

make test-mermaid

Serve generated files#

python3 -m http.server --directory dist 8000

Use Make helpers#

Show all helper targets:

make help

Generate or preview the bundled example:

make bundle
make bundle THEME=paper
make offline-bundle
make preview PORT=8000
make example PORT=8080

Generate or run external documentation with Podman:

make bundle-container SOURCE=/absolute/path/to/docs
make run-container SOURCE=/absolute/path/to/docs PORT=8080

See the Make helper guide for variables and complete workflows.

Enable Mermaid in container builds with make bundle-container MERMAID=1 or make runtime-image MERMAID=1. With an installed host renderer, use make offline-bundle MERMAID=1 for both hosted and offline diagrams.