# DEM-Engine documentation

Start with the [documentation index](index.rst), [installation](installation.rst),
or [Python quickstart](python/quickstart.rst). Maintainers can find
[hosting options](developer/hosting.rst) and [wheel packaging](developer/packaging.rst)
in the developer guide.

## Building and previewing

The documentation site combines:

- authored Sphinx pages for installation, concepts, and Python usage;
- a C++ API reference generated by Doxygen and Breathe; and
- a static Python API reference generated from the installed pybind11 module.

Generated HTML, Doxygen XML, and other files under `docs/_build/` are ignored
by Git.

## Install the documentation tools

Doxygen must be installed as an executable. Create a Python environment and
install the Sphinx dependencies:

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

Install Doxygen through the operating system or Conda if it is not already
available:

```bash
conda install -c conda-forge doxygen
```

Check the toolchain:

```bash
doxygen --version
sphinx-build --version
```

## Build the complete site

From the repository root:

```bash
/usr/bin/make -C docs html
```

Using `/usr/bin/make` is helpful on machines where `make` is aliased to
`ninja`. This command:

1. syntax-checks the Python examples;
2. generates Doxygen XML for the C++ public API; and
3. builds the complete Sphinx HTML site with warnings treated as errors.

The resulting entry page is:

```text
docs/_build/html/index.html
```

To remove generated output:

```bash
/usr/bin/make -C docs clean
```

The equivalent CMake documentation target is:

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

## Regenerate the Python API reference

Normal HTML builds use the committed `docs/python/reference.rst` and therefore
do not import DEME or require a CUDA GPU.

Regenerate that file after changing pybind11 signatures or docstrings. First
build and stage the Python extension:

```bash
cmake -S . -B build-python \
    -DDEME_BUILD_PYTHON=ON \
    -DCMAKE_BUILD_TYPE=Release
cmake --build build-python --target _deme --parallel
cmake --install build-python \
    --component python \
    --prefix /tmp/deme-python-reference
```

Then run the generator with the same Python interpreter used to build the
extension:

```bash
PYTHONPATH=/tmp/deme-python-reference \
    /usr/bin/make -C docs python-reference
```

Finally, rebuild the site:

```bash
/usr/bin/make -C docs html
```

Do not edit `docs/python/reference.rst` directly. Improve the corresponding
docstring in `src/DEM/python/bindings.cpp`, rebuild the extension, and
regenerate the page.

## Preview on the same machine

Run a local HTTP server from the repository root:

```bash
python3 -m http.server 8000 \
    --bind 127.0.0.1 \
    --directory docs/_build/html
```

Open <http://127.0.0.1:8000/> in a browser. Stop the server with `Ctrl+C`.

## Preview a remote build through SSH

Start the same loopback-only HTTP server on the remote build machine. From the
local workstation, create an SSH tunnel:

```bash
ssh -L 8000:127.0.0.1:8000 username@remote-host
```

Keep the SSH connection open and visit <http://127.0.0.1:8000/> locally.

For a trusted local network, the server can instead listen on every interface:

```bash
python3 -m http.server 8000 \
    --bind 0.0.0.0 \
    --directory docs/_build/html
```

The site is then available at `http://HOST_IP:8000/`, subject to firewall
rules. Prefer SSH forwarding when the remote host should not expose the
documentation server publicly.