# Read the Docs

The documentation builds in two environments:

| Target | Triggered by | Source of truth for benchmark data |
|---|---|---|
| **GitHub Pages** (`https://methods.nirs4all.org/`) | Push to `main` via `.github/workflows/docs.yml` | Live `benchmarks/cross_binding/results/full_matrix.csv` if present, else `docs/_static/bench-data.json` |
| **Read the Docs** (`pls4all.readthedocs.io`) | RTD webhook on every push | `docs/_static/bench-data.json` (the committed fallback) |

The two builds share the same Sphinx config (`docs/conf.py`).

## One-time RTD setup

1. **Push** `.readthedocs.yaml` and `docs/_static/bench-data.json` to
   `main`. Both already live in this repo.
2. Sign in at <https://readthedocs.org/> and **Import a Project** →
   GitHub provider → pick `GBeurier/pls4all`.
3. In **Admin → Advanced settings**:
   - *Documentation type*: Sphinx HTML.
   - *Privacy level*: Public.
   - *Default branch*: `main`.
4. Optional: in **Admin → Domains** add a custom CNAME
   (e.g. `docs.pls4all.io`).
5. Run the first build (it auto-triggers after import). Logs land at
   `https://readthedocs.org/projects/pls4all/builds/`.

After the first green build the URL is
`https://pls4all.readthedocs.io/`. Versioned snapshots live at
`/en/<branch-or-tag>/`.

## Build behaviour

The RTD container clones the repo, installs `docs/requirements.txt`
(Sphinx + myst-parser + linkify), then runs:

```
sphinx-build -b html docs $READTHEDOCS_OUTPUT/html
```

`docs/conf.py:setup()` automatically detects that the benchmark CSV
isn't present (RTD does not clone LFS objects or run the benchmark
matrix) and falls back to `docs/_static/bench-data.json`, which is a
committed snapshot regenerated by the local benchmark runner via
`docs/_extras/build_landing.py`.

## Refreshing the bundled benchmark snapshot

```bash
# After re-running the cross-binding benchmark:
python docs/_extras/build_landing.py \
    --results benchmarks/cross_binding/results \
    --out    docs/_static/bench-data.json

# After regenerating method pages from registry / docstrings / CSV:
python docs/_extras/build_methods.py

git add docs/_static/bench-data.json docs/methods/
git commit -m "Refresh RTD-bundled benchmark snapshot + method pages"
```

The next push triggers the RTD webhook which rebuilds the docs against
the fresh JSON.

## When RTD builds fail

| Symptom | Likely cause | Fix |
|---|---|---|
| `ModuleNotFoundError: yaml` while building methods | `pyyaml` not in `docs/requirements.txt` | RTD doesn't run `build_methods.py`; only commit the *generated* pages |
| `toctree contains reference to nonexisting document` | A new method page added to `methods/` but `methods/index.md` not regenerated | Run `python docs/_extras/build_methods.py` and commit |
| `landing.html: bench_data_json is undefined` | `docs/_static/bench-data.json` not committed | Commit the JSON snapshot |
| Build times out | The benchmark CSV got committed by accident (it's ~1.4 MB and unused on RTD) | Re-check `.gitignore`; keep the JSON fallback only |

## Local mirror of an RTD build

```bash
# Reproduce the RTD container build locally:
pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html
xdg-open docs/_build/html/index.html
```

This is the *same* command RTD runs, so anything that fails locally
will also fail on RTD.