Building Documentation Locally

The documentation is built with Sphinx and hosted on GitHub Pages. The dev environment (pixi shell) includes all necessary tools so no extra installation is needed.

With pixi (recommended)

The easiest way to build and preview the documentation is with the docs pixi task. It builds the documentation and immediately starts a local HTTP server so you can view the result in your browser:

pixi run docs

Then open http://127.0.0.1:8000 in your browser. The task runs two steps in sequence:

1. sphinx-build docs docs/_build/html — compiles the documentation

2. python -m http.server 8000 (from docs/_build/html) — serves it locally

Press Ctrl+C to stop the server.

If you want to run the two steps individually you can also use the underlying tasks directly:

pixi run _docs-build   # build only
pixi run _docs-serve   # serve only (requires a prior build)

Raw commands

If you prefer running the commands directly without pixi tasks (e.g. inside an active pixi shell), the equivalent steps are:

sphinx-build docs docs/_build/html
cd docs/_build/html
python -m http.server 8000

Then open http://127.0.0.1:8000 in your browser. Use a different port number if 8000 is already in use on your machine.

Live Preview

For a live-reloading preview while editing, use sphinx-autobuild (install it separately if needed):

pip install sphinx-autobuild
sphinx-autobuild docs docs/_build/html

Structure

The documentation source lives in the docs/ directory:

File / folder	Purpose
conf.py	Sphinx configuration
index.md	Landing page and top-level toctree
get_started/	Installation instructions
preprocessing.md	Pre-processing examples
execution.md	Execution examples
postprocessing/	Post-processing and map plotting
developing/	Developer documentation (this section)
about.md	About page

Pages are written in MyST Markdown, which extends standard Markdown with Sphinx directives.