Building the documentation

The concise build, Python-reference regeneration, and local/remote preview commands are collected in docs/README.md.

Prerequisites

Install Doxygen through the operating system or Conda, then create an isolated Python environment:

python3 -m venv .venv-docs
. .venv-docs/bin/activate
python -m pip install -r docs/requirements.txt

Standalone build

make -C docs html

Open docs/_build/html/index.html in a browser.

Regenerating the Python API reference

After building and installing the current deme extension into the active Python environment, regenerate the static reference from pybind11 signatures and docstrings:

make -C docs python-reference
make -C docs html

The generated docs/python/reference.rst is committed so normal documentation builds do not import the native extension or require a GPU. Improve descriptions in src/DEM/python/bindings.cpp and regenerate rather than editing the reference page directly.

CMake target

When configuring the complete project:

cmake -S . -B build-docs -DDEME_BUILD_DOCS=ON
cmake --build build-docs --target docs

Documentation policy

  • Doxygen parses the public C++ headers and emits XML.

  • Sphinx and Breathe render the C++ API alongside authored guides.

  • Worker internals and CUDA kernels belong in architecture pages rather than the public API reference.

  • New public functions should describe intent, parameters, units, frames, setup/runtime restrictions, and return values.

  • The HTML build uses warnings-as-errors so broken API references do not silently enter published documentation.

See Hosting the documentation for publication options and source-tree organization, and Python wheel maintenance for Python wheel maintenance.