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

# 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

# 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.