# Documentation — build, workflow, and style guide

This file explains **how the docs are built**, their **dependencies**, the **expected workflow**, and our **style choices** (including how we embed reStructuredText in Doxygen comments).

---

## TL;DR (quick start)

```bash
# 1) Install Python deps
pip install -r requirements.txt

# 2) Make sure doxygen is installed (e.g., apt-get install doxygen)

# 3) Build and preview
./scripts/build_docs.sh --serve --open
```

What you get:
- Doxygen XML is written under `build-docs/docs/_build/doxygen/xml/`
- Sphinx HTML is written to `build-docs/docs/html/`
- Exhale generates an API index under `docs/api/` (this folder is **regenerated each build**)

> **Note**: `build_docs.sh` now **always performs a clean build** by removing `build-docs/` and `docs/api/` before rebuilding.

---

## Dependencies

- **Sphinx** + **Furo theme** for the HTML site.
- **Breathe** to bridge Doxygen XML into Sphinx.
- **Exhale** to generate a consistent, tidy C++ API tree under `docs/api/`.
- **MyST-Parser** to allow Markdown files in the docs.
- **Doxygen** to parse C/C++/Fortran sources and emit XML for Breathe.

Install Python dependencies with:
```bash
pip install -r requirements.txt
```

The versions are pinned broadly in `requirements.txt` and are compatible with Sphinx 7+.

---

## Source layout and build outputs

```
docs/                  # Sphinx project root (this folder)
├─ conf.py             # Sphinx configuration (Furo theme; Breathe/Exhale integration)
├─ index.rst           # Landing page
├─ memory.rst          # (example content)
├─ api/                # 🔁 generated by Exhale each build (deleted & recreated)
└─ README.md           # ← this file

build-docs/            # out-of-tree build area
└─ docs/
   ├─ html/            # final site (open index.html here)
   ├─ doctrees/        # Sphinx cached state
   └─ _build/doxygen/  # Doxygen outputs (XML under ./xml/)
```

---

## How the pipeline fits together

1. **Doxygen** scans `src/` (C/C++/Fortran) and writes **XML**.
   - Config template: `Doxyfile.in` (no CMake configure step is required by the script).
   - We pass normalized paths so the build stays relocatable.
2. **Breathe** reads that XML and exposes it as Sphinx directives/roles.
3. **Exhale** walks the symbol graph and writes a clean **API index** beneath `docs/api/`.
4. **Sphinx** renders everything to **HTML** using the **Furo** theme.

Key configuration highlights (see `docs/conf.py`):
- **Theme:** `furo` (can override via `SPHINX_THEME` env var).
- **Strictness:** set `SPHINX_STRICT=1` to make Sphinx warnings fail the build.
- **TODOs:** set `SPHINX_TODOS=1` to include `.. todo::` blocks in the HTML.
- **Graphviz:** diagrams render as SVG when using `.. graphviz::`.
- **Auto-section labels:** unique refs by document (`:ref:` works across files).

---

## Building the docs

### Using the helper script (preferred)

```bash
# For a clean build: removes build-docs/ and docs/api/
./scripts/build_docs.sh --clean

# Serve locally (http://localhost:8000) and try to open a browser tab
./scripts/build_docs.sh --serve --open

# Force rebuild regardless of timestamps
./scripts/build_docs.sh --force
```

Under the hood the script:
- regenerates `Doxyfile` into `build-docs/docs/Doxyfile`
- runs Doxygen (unless `--no-doxygen`)
- exports `DOXYGEN_XML_DIR` so Breathe/Exhale see the right XML path
- runs `sphinx-build` with a parallel job count
- **cleans** `build-docs/` and `docs/api/` _before_ building (project policy)

### Using CMake (optional)

There is also a simple CMake target for docs:
```bash
cmake -S docs -B docs/build
cmake --build docs/build --target docs
```
This uses the `find_package(Sphinx REQUIRED)` path and builds HTML, but the script above remains the canonical developer workflow.

---

## Authoring style & conventions

### 1) Titles and structure
- Use reST (`.rst`) for most pages; Markdown via MyST is supported when convenient.
- Use sentence-style capitalization for headings.
- Keep section levels consistent (`=`, `-`, `^`, `~` underlines).

### 2) Code blocks and languages
- Prefer explicit languages (`.. code-block:: cpp`, `python`, `yaml`, etc.).
- For short inline literals, use double backticks: ``like_this``.
- Long command lines go in `bash` blocks; keep lines wrapped ≤ 100 chars.

### 3) Admonitions and notes
- `.. note::`, `.. warning::`, `.. tip::` are encouraged for key points.
- Keep admonition bodies short; link out for details.

### 4) Cross-references
- Use `:ref:` for doc pages/sections.
- For API, prefer Breathe/Exhale roles, e.g. ``:cpp:func:`ns::foo``` when convenient.
- Autosection labels are enabled across documents; headings can be referenced safely.

### 5) Embedding reST inside Doxygen comments (our standard)
We enable Doxygen’s **embedded reST** via aliases (`@rst`/`@endrst`) with *leading-asterisk* support. This lets you write pretty Sphinx blocks directly inside `/** */` comments without fighting indentation.

**Example (exact style we use):**
```text
 * @rst 
*.. code-block:: cpp
*
*    exchange_ghosts(rho, mesh, cart_comm); // X±, Y±, Z± slabs
* @endrst
```
Tips:
- Keep one blank `*` line between the directive and code body.
- The alias handles the leading `*` characters automatically.
- Use reST roles inside too (links, math, etc.).

### 6) Diagrams
- Use `.. graphviz::` for simple graphs; prefer small, focused diagrams.
- Default output is SVG for crisp scaling in the Furo theme.

---

## CI and publishing

A `docs.yml` workflow builds the site and can deploy to `gh-pages`. Locally you can preview with `--serve`; in CI use `--force` for deterministic, clean builds. Toggle strictness with `SPHINX_STRICT=1` to treat warnings as errors.

---

## Troubleshooting

- **`doxygen not found`** → install it (Linux: `apt-get install doxygen`, macOS: `brew install doxygen`).
- **Empty API pages** → ensure headers/sources live under `src/` and symbols aren’t excluded.
- **Link targets not found** → build once with `SPHINX_STRICT=1` to catch broken refs.
- **Unicode in code samples** → ensure your editor saves files as UTF‑8.