Building Documentation

The narrative documentation and the Python API pages are written in reStructuredText and generated by Sphinx. The tutorial pages are the example notebooks (via nbsphinx) and the C++ example programs (via literalinclude). The C++ API reference is generated from Doxygen comments with the Breathe and Exhale Sphinx plugins. The generated HTML is GitHub Pages-ready.

Build with pixi

Pixi installs the documentation toolchain, generates the Python and C++ API pages, runs Sphinx, and copies the final site into build/docs:

pixi run build-docs

The Python API generator imports pylupnt. If python/pylupnt/_pylupnt*.so is missing, build the bindings first (build-docs already depends on build-py, so this is only needed for a manual build):

pixi run build-py

The command writes build/docs/.nojekyll so GitHub Pages serves generated directories such as _static without Jekyll filtering.

Previewing locally

Serve the generated site and open it in a browser:

python -m http.server 8000 --directory build/docs

then visit http://localhost:8000. A local server (rather than opening the HTML files directly) is recommended so in-page search and the interactive visualizations load correctly.

Tutorial outputs

nbsphinx is configured with nbsphinx_execute = "never", so the rendered notebooks display the outputs stored in each .ipynb — the docs build does not re-run them. After changing an example or an API it depends on, refresh those stored outputs in place:

pixi run render-notebooks                 # all notebooks
pixi run render-notebooks -- --only ex16  # a subset

Interactive outputs render from a CDN at view time, so a network connection is needed to see them: Plotly figures (ex12, ex14–ex16) pull plotly.js, and the Cesium scenes (ex13) — self-contained HTML written to docs/_static/cesium_scenes/ and linked from the page — pull CesiumJS. Static Matplotlib figures are embedded as images and always render.

Manual build

If you are not using pixi, first build the C++ library and Python bindings, then install the Python and system documentation dependencies and run the build script:

cd docs
pip install -r requirements.txt
brew install doxygen pandoc          # macOS
sudo apt-get install doxygen pandoc  # Linux
python make_docs.py

The generated HTML is written to the repository-level build/docs folder.