docs(rtd): native version selector for exact releases

.readthedocs.yaml

@@ -21,17 +21,33 @@ sphinx:
 # is labelled with the version it actually documents, and a non-tag build renders the
 # "unreleased development version" banner (docs/source/_templates/layout.html).
 #
-# The rest is Read the Docs PROJECT ADMIN, not repo config -- it cannot be set from
-# this file and has to be done once in the RTD dashboard:
-#   1. Admin > Versions: activate the release tag versions (v1.0.3, ...). RTD only
-#      builds tags it has been told to activate; without this there is nothing for
-#      `stable` to point at.
-#   2. Admin > Settings > Default version: `stable` (not `latest`), so the bare
-#      https://aaanalysis.readthedocs.io/ URL and search results land readers on the
-#      newest *release* rather than the dev branch. RTD maintains the `stable` alias
-#      automatically from the highest active semver tag.
-#   3. Admin > Settings > Default branch: `master` (the `latest` alias).
+# Version selector: the sphinx_rtd_theme (>= 3.0) sidebar <select> and the Read the
+# Docs flyout are both filled at page-load time from the Read the Docs Addons API with
+# every ACTIVE version, so nothing in this repository lists versions. 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
+#
+# Which versions are active is Read the Docs PROJECT ADMIN, not repo config -- it
+# cannot be set from this file and has to be done once in the RTD dashboard
+# (https://app.readthedocs.org/dashboard/aaanalysis/):
+#   1. Versions: activate every release tag (v1.0.0, v1.0.1, v1.0.2, v1.0.3, v1.1.0).
+#      Each activation triggers a build of that tag's own commit, so its docs never
+#      change afterwards. RTD only builds tags it has been told to activate.
+#   2. Automation Rules: add one rule so future tags need no manual step --
+#        Match: Custom match  ^v\d+\.\d+\.\d+$   Version type: Tag
+#        Action: Activate version
+#      (and optionally a second rule with the same match and "Set version as default",
+#      which moves the bare https://aaanalysis.readthedocs.io/ URL to the new release).
+#   3. Settings > Default version: `stable` (not `latest`), so the bare URL and search
+#      results land readers on the newest *release* rather than the dev branch. RTD
+#      maintains the `stable` alias automatically from the highest active semver tag.
+#   4. Settings > Default branch: `master` (the `latest` alias).
+#   5. Settings > Addons: keep "Flyout" and "Version selector" enabled (default).
 # Tag naming is `vX.Y.Z`; RTD sorts `stable` by semver, so consistent tags matter.
+# Tags are built from their own commit: a tag whose docs build fails on today's RTD
+# builders cannot be repaired from master.
 
 python:
   install:

CONTRIBUTING.rst

@@ -521,6 +521,13 @@ To cut a release:
         Description:   the release_notes / CHANGELOG entry for this version
       -> Publish release
 
+   The new tag also becomes a documentation version: a Read the Docs automation rule
+   (``^v\d+\.\d+\.\d+$`` -> *Activate version*, see ``.readthedocs.yaml``) activates
+   and builds it, so https://aaanalysis.readthedocs.io/en/vX.Y.Z/ appears in the
+   version selector and ``stable`` moves to it. Check that the tag's build is green
+   on https://app.readthedocs.org/projects/aaanalysis/builds/ ; a tag is built from
+   its own commit, so a red build there cannot be fixed from ``master``.
+
 5. **Verify the upload.**
 
    Confirm the version, files and metadata on https://pypi.org/project/aaanalysis/ ,

docs/source/_static/js/version_switch.js

@@ -0,0 +1,33 @@
+/* Keep the current page when switching versions in the sidebar selector.
+ *
+ * sphinx_rtd_theme (>= 3.0) fills the <select> under the logo from the Read the Docs
+ * Addons API ("readthedocs-addons-data-ready"), so the version list itself is native
+ * and needs no maintenance here. The theme, however, links every option to the
+ * *root* of the chosen version. Read the Docs' own flyout resolves the same page in
+ * the other version instead (version root + the "readthedocs-resolver-filename"
+ * meta tag that Read the Docs injects when serving the page), so this script applies
+ * the same rule to the sidebar options. A page that does not exist in the chosen
+ * version falls through to Read the Docs' 404 handling for that version.
+ *
+ * Outside Read the Docs (local builds) the event never fires and nothing happens.
+ */
+document.addEventListener("readthedocs-addons-data-ready", function (event) {
+  const meta = document.querySelector('meta[name="readthedocs-resolver-filename"]');
+  const filename = meta ? meta.getAttribute("content") : null;
+  if (!filename) {
+    return;
+  }
+  // The theme's own listener (registered later) builds the <select>; run after it.
+  queueMicrotask(function () {
+    const options = document.querySelectorAll(
+      "div.switch-menus > div.version-switch select > option[data-url]",
+    );
+    const page = filename.replace(/\/index\.html$/, "/").replace(/^\//, "");
+    options.forEach(function (option) {
+      const root = option.dataset.url;
+      if (root) {
+        option.dataset.url = new URL(page, root.replace(/\/*$/, "/")).href;
+      }
+    });
+  });
+});

docs/source/_templates/layout.html

@@ -21,7 +21,8 @@
     on PyPI yet, so features documented here may be missing from the version you
     installed, and may still change.
     For the documentation matching the latest release, switch to
-    <a href="https://aaanalysis.readthedocs.io/en/stable/">stable</a>.
+    <a href="https://aaanalysis.readthedocs.io/en/stable/">stable</a>; the version
+    selector in the sidebar also lists every release (v1.0.0, v1.1.0, ...).
   </p>
 </div>
 {% endif %}

docs/source/conf.py

@@ -50,6 +50,12 @@
 rtd_version = os.environ.get("READTHEDOCS_VERSION", "")
 rtd_version_type = os.environ.get("READTHEDOCS_VERSION_TYPE", "")
 is_dev_build = rtd_version_type != "tag"
+on_rtd = os.environ.get("READTHEDOCS", "") == "True"
+
+# Canonical URL of the version being built (https://aaanalysis.readthedocs.io/en/<version>/).
+# Read the Docs sets it per build; it feeds <link rel="canonical"> so search engines
+# and citations resolve to the versioned page. Empty for local builds.
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
 
 repository_url = "https://github.com/breimanntools/aaanalysis"
 pygments_style = "sphinx"
@@ -166,9 +172,19 @@
 # -- Options for HTML output -------------------------------------------------
 html_title = "AAanalysis"
 html_theme = 'sphinx_rtd_theme'
+# Version selector. sphinx_rtd_theme >= 3.0 no longer draws the version under the
+# logo ("display_version" is gone); instead, on Read the Docs it renders a version
+# <select> in the sidebar header, filled at page-load time from the Read the Docs
+# Addons API with every *active* version (latest, stable, v1.0.0, v1.1.0, ...). The
+# list is therefore native and maintenance-free: activating a release tag in the RTD
+# dashboard (or the automation rule in .readthedocs.yaml) is all a new version needs.
+# "flyout_display": "hidden" keeps the theme from drawing a second, duplicate flyout
+# next to the Read the Docs one in the bottom-right corner.
 html_theme_options = {
     "logo_only": True,
-    "display_version": True,
+    "version_selector": True,
+    "language_selector": False,
+    "flyout_display": "hidden",
     "prev_next_buttons_location": "bottom",
     "style_external_links": False,
     "style_nav_header_background": "#343131",
@@ -180,6 +196,9 @@
 }
 html_static_path = [os.path.join(path_source, '_static')]
 html_css_files = ['css/style.css', 'css/notebook.css']
+# Makes the sidebar version <select> keep the current page when switching versions
+# (the theme links each option to the version root). No-op outside Read the Docs.
+html_js_files = ['js/version_switch.js']
 html_show_sphinx = False
 html_logo = "_artwork/logos/logo_white_large.png"
 html_favicon = "_artwork/logos/favicon_white.svg"
@@ -196,6 +215,12 @@
     'aa_release': release,
 }
 
+# The theme gates its Read the Docs integration (the addons <meta> tag and the sidebar
+# version selector) on this flag. Read the Docs used to inject it into every Sphinx
+# build; its documentation now asks projects to set it themselves.
+if on_rtd:
+    html_context["READTHEDOCS"] = True
+
 html_meta = {
     'google-site-verification': 'Rk3T0-H7cpFf5UxXiL4-LMS0WN7FIyU_3NiomozORV0',
     'favicon': "_artwork/logos/favicon_white.png"

docs/source/index/CONTRIBUTING_COPY.rst

@@ -521,6 +521,13 @@ To cut a release:
         Description:   the release_notes / CHANGELOG entry for this version
       -> Publish release
 
+   The new tag also becomes a documentation version: a Read the Docs automation rule
+   (``^v\d+\.\d+\.\d+$`` -> *Activate version*, see ``.readthedocs.yaml``) activates
+   and builds it, so https://aaanalysis.readthedocs.io/en/vX.Y.Z/ appears in the
+   version selector and ``stable`` moves to it. Check that the tag's build is green
+   on https://app.readthedocs.org/projects/aaanalysis/builds/ ; a tag is built from
+   its own commit, so a red build there cannot be fixed from ``master``.
+
 5. **Verify the upload.**
 
    Confirm the version, files and metadata on https://pypi.org/project/aaanalysis/ ,

docs/source/index/citations.rst

@@ -21,3 +21,12 @@ If you use **AAanalysis** in your work, please cite the respective publication a
    [Breimann25]_  Breimann and Kamp *et al.* (2025),
    *Charting γ-secretase substrates by explainable AI*,
    `Nature Communications <https://www.nature.com/articles/s41467-025-60638-z>`__.
+
+**Documentation for an exact release**: the version selector in the sidebar lists every
+release, and each one has a permanent URL of the form
+``https://aaanalysis.readthedocs.io/en/vX.Y.Z/`` (for example
+`v1.0.0 <https://aaanalysis.readthedocs.io/en/v1.0.0/>`__). Those pages are built once from
+the release tag and do not change when newer versions are published, so cite them when a
+result depends on a specific AAanalysis version. By contrast,
+`stable <https://aaanalysis.readthedocs.io/en/stable/>`__ always tracks the newest release
+and `latest <https://aaanalysis.readthedocs.io/en/latest/>`__ the development branch.