docs: migrate to uv, retire Read the Docs, one page per solver

[joglekara]

Why

The README pointed at env.yaml, env_gpu.yaml and requirements.txt — all deleted back in d18b57a. The documented install path had been broken for a while. This swaps it for uv and then brings the rest of the docs back in line with the code.

Install and build

• README and docs/source/usage.md use uv sync --extra dev, uv add, and uv run run.py, matching what CI actually does.
• Read the Docs retired. GitHub Pages is what docs.yaml deploys and what CLAUDE.md references. Two doc sites drifting apart is a trap.
  • ⚠️ Manual step: the RTD project still exists and will keep serving its last build at adept.readthedocs.io. It needs deactivating in the RTD dashboard so the stale copy doesn't outrank the new site.
• Docs toolchain consolidated onto the docs extra; docs/requirements.txt deleted. The extra was missing myst-parser — which conf.py loads, and without which none of the markdown pages parse — and carried sphinx_autodoc_typehints, which was never listed in extensions. The old requirements.txt also capped sphinx at 7.x, so those ceilings became floors. Net lockfile change is +myst-parser and its three deps, -sphinx-autodoc-typehints; nothing else moved.
• docs.yaml now builds with uv run --locked --extra docs, which installs adept itself. autodoc could not import the package before, so ergoExo.html and ADEPTModule.html were rendering empty on the live site.

Build warnings: 9 → 0

• myst_heading_anchors was never set, so no heading anchors were generated at all and both #species-multispecies-configuration links were dead.
• html_css_files referenced _static/custom.css in a directory that didn't exist — a guaranteed 404. Added, and it widens the content column so the config tables stop being truncated at the theme's 800px default.
• Dropped the unsupported display_version theme option and a duplicated html_static_path, fixed a leading transition in faq.md, and fixed an RST-breaking `eqx.Module`s in an ADEPTModule docstring.

One page per solver

Every solver now has an overview page stating the equations solved, the boundary conditions, the forcing, what gets written out, and how to run it.

usage/vlasov1d.md, usage/vlasov1d2v.md and usage/tf1d.md are folded into those pages; usage/ keeps only initialization.md and cloud.md. New overview pages for spectrax1d, hermite_legendre_1d, pic1d, tf1d and vlasov1d2v, plus a config reference for pic1d. Three config references (vfp1d, spectrax1d, hermite_legendre_1d) were orphaned from every toctree and reachable only by direct URL.

The boundary-condition tables surface things that were previously only visible in code comments:

• vlasov1d's exponential velocity push is periodic in v and wraps the forward tail onto the −v edge
• vfp1d requires boundary: reflective under spherical geometry and raises otherwise
• lpse2d builds its absorbing layer as exp(-α·dt·(1-env)) over boundary_width/5, configured per axis
• hermite_legendre_1d confines its Legendre window with a rank-2 Dirichlet penalty
• pic1d has no velocity boundary at all, which is its structural advantage over the grid solvers

Corrections

• dev_guide.md rewritten. It documented utils/runner.py, get_helpers() and cfg["mode"] — none of which exist — and is now built around the actual ergoExo/ADEPTModule lifecycle.
• tf1d equations corrected. They had a field term divided by density and a source-free pressure equation. The implementation has (q/m)E and carries a 2nu(q/m)E field-work term, so p is not a pure pressure. Documented as such.
• tests.md rewritten. It listed four test files by name and missed eight suites.

Cleanup

Dead configs (configs/es1d, configs/sh2d — solver keys _base_.py doesn't dispatch) and strays (Untitled.ipynb, .git_commit). configs/ is now closed against the dispatcher: every remaining directory maps to a live solver: key.

Verification

• Docs build clean, 0 warnings, verified after each step including after the usage-page deletions — no dangling references.
• pre-commit run --all-files green.
• tests/test_base (30) and tests/test_vlasov1d2v/test_1d_limit (3) pass; tests/import_test.py passes.

Not done

The CI coverage gap is left alone deliberately. test_vlasov1d2v, test_vlasov2d, test_tf1d and test_cloud have no CI job — 14 test files never run on a PR. tests.md states this explicitly rather than implying coverage. Worth noting that test_tf1d exceeded a 10-minute local timeout (test_against_vlasov.py runs a full Vlasov sim), so those suites likely want the slow marker or a nightly job rather than a per-PR one.

🤖 Generated with Claude Code