docs(rtd): native version selector for exact releases

[breimanntools]

Summary

Users can now switch between documentation for exact AAanalysis releases (v1.0.0, v1.0.1, ..., v1.1.0) as well as latest and stable, using the native Read the Docs version selector. Nothing in the repository lists versions: the sphinx_rtd_theme (3.0) sidebar dropdown and the Read the Docs flyout are filled at page-load time from the Read the Docs Addons API with every active version, so future tags need no source edit.

URLs follow the standard layout:

• https://aaanalysis.readthedocs.io/en/latest/ (master, development)
• https://aaanalysis.readthedocs.io/en/stable/ (highest active release tag)
• https://aaanalysis.readthedocs.io/en/v1.0.0/ (exactly the v1.0.0 tag, immutable)

Changes

• docs/source/conf.py: drop the removed display_version theme option (sphinx_rtd_theme 3.0 warns on it), enable version_selector, hide the theme's duplicate flyout, set html_baseurl from READTHEDOCS_CANONICAL_URL and html_context["READTHEDOCS"] as the Read the Docs docs now require, and load js/version_switch.js.
• docs/source/_static/js/version_switch.js (new): the theme links every dropdown option to the version root; this rewrites the options to the same page in the chosen version (version root + the readthedocs-resolver-filename meta tag), the rule Read the Docs' own flyout uses. A page that does not exist in the target version falls through to Read the Docs' 404 for that version. No-op outside Read the Docs.
• Dev banner (_templates/layout.html) and the Citation section on the landing page point readers at the selector and the immutable /en/vX.Y.Z/ URLs.
• .readthedocs.yaml comments and the CONTRIBUTING release step document the dashboard setup and the post-release check.

Verified with a local Sphinx build under the Read the Docs environment variables: no theme-option warning, the addons meta tag, the sidebar version-switch container, the script and the canonical link are all rendered.

Git tags

v1.0.1 and v1.0.2 had no git tag, so Read the Docs could not build them. Annotated tags were created at the release commits (matched to the PyPI upload dates) and pushed:

Tag	Commit	PyPI release
v1.0.1	1cc9d0f "Release v1.0.1"	2025-01-29
v1.0.2	43eeaff "Release version 1.0.2"	2025-06-17

Required Read the Docs dashboard configuration (one-time, cannot be set from the repo)

At https://app.readthedocs.org/dashboard/aaanalysis/ :

1. Versions: activate v1.0.0, v1.0.1, v1.0.2, v1.0.3, v1.1.0. Each activation builds that tag's own commit once; the result never changes afterwards.
2. Automation Rules: add a rule with Custom match ^v\d+\.\d+\.\d+$, version type Tag, action Activate version. Future release tags then appear in the selector automatically. Optionally a second rule with the same match and Set version as default.
3. Settings: Default version stable (not latest), Default branch master.
4. Settings > Addons: keep Flyout and Version selector enabled (default).

Note: a tag is built from its own commit, so a tag whose docs build fails on today's builders cannot be repaired from master. v1.0.0 builds with its 2024 configuration (ubuntu-20.04, Python 3.9, Sphinx 5.3 pins); v1.0.1 onward pin Sphinx 8.1.

Acceptance criteria

• Visible version selector on RTD (sidebar dropdown + RTD flyout)
• latest and stable remain available
• v1.0.0 selectable, leading to /en/v1.0.0/ (after dashboard activation)
• Exact release docs are immutable (built once from the tag)
• Future tags need no hard-coded list (automation rule + Addons API)
• Existing build and navigation unchanged (local build green)
• Dashboard configuration documented here and in .readthedocs.yaml

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.39%. Comparing base (fc8e21e) to head (579b8d3).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #597   +/-   ##
=======================================
  Coverage   95.39%   95.39%           
=======================================
  Files         222      222           
  Lines       23387    23387           
  Branches     4073     4073           
=======================================
  Hits        22309    22309           
  Misses        631      631           
  Partials      447      447           

Components	Coverage Δ
cpp_core	95.97% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.