Docs: executable Jupyter notebooks + Python API reference (myst-nb + autodoc)

[grzanka]

Part of #130. Complements the prose guide in #116 (purpose/role) with hands-on, runnable Python docs.

Context

The Sphinx site (docs/source, pydata-sphinx-theme, deployed by .github/workflows/docs.yml) currently has no executable examples or generated Python API reference. With a first-class Python package (companion issues), we want runnable notebooks and an autogenerated API reference, executed in CI so docs can never go stale.

Proposed change

• Add to docs/source/requirements.txt: myst-nb (+ myst-parser) and Sphinx autodoc + napoleon + autodoc_typehints; enable in conf.py.
• Execute notebooks at build time (myst-nb) against the freshly built wheel — doubles as integration testing.
• Notebook set:
  1. Quickstart — install, one STP value, one curve.
  2. Programs & data sources — PSTAR/ASTAR/MSTAR/ICRU comparison on one plot.
  3. Energy tables & CSDA range — DataFrame workflows, CSV export.
  4. Custom compounds & materials — showcases the config/custom-compound API (Public custom-compound config builder + flat forward/inverse/peak wrappers #123) and material accessors (Expose nucleon number, atom mass, density and is-gas in the public header #119 + child).
  5. Ion/material catalog — browse the generated enums, valid combinations (Add query API for valid (program, ion, material) combinations to support GUI/frontend development #79).
  6. Bragg-curve example — a realistic proton/ion-therapy use case.
• Binder/Colab badges so notebooks run in-browser.

Acceptance criteria

• myst-nb + autodoc wired into the Sphinx build; API reference generated from docstrings.
• Notebooks execute cleanly in CI against the built wheel (failures break the docs build).
• Installation page (pip + extras) and notebook gallery published to GitHub Pages.
• Binder/Colab entry points work.

References

Complements #116 · depends on the nanobind core + scientific-layer issues under #130 · relates to #117, #79.

---

Filed via Claude Code (model: Claude Opus 4.8) as part of the libdedx → libamtrack integration & Python-packaging plan.