From 579b8d3d289d9b9cc3841f9e8a1a1848296235f0 Mon Sep 17 00:00:00 2001 From: Stephan Breimann Date: Thu, 24 Sep 2026 12:02:34 +0200 Subject: [PATCH] docs(rtd): native version selector for exact releases Read the Docs Addons already fill the sphinx_rtd_theme (3.0) sidebar version 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: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b5a3c25b5..0f89a6d82 100644 --- a/CONTRIBUTING.rst +++ b/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/ , diff --git a/docs/source/_static/js/version_switch.js b/docs/source/_static/js/version_switch.js new file mode 100644 index 000000000..e890506db --- /dev/null +++ b/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 ; 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; + } + }); + }); +}); diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 77425fee8..4b30b476c 100644 --- a/docs/source/_templates/layout.html +++ b/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 - stable. + stable; the version + selector in the sidebar also lists every release (v1.0.0, v1.1.0, ...).

{% endif %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 4a2694060..ffd320687 100755 --- a/docs/source/conf.py +++ b/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//). +# Read the Docs sets it per build; it feeds 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 +# 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 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" diff --git a/docs/source/index/CONTRIBUTING_COPY.rst b/docs/source/index/CONTRIBUTING_COPY.rst index fcd2aa1dd..e310d4e0f 100644 --- a/docs/source/index/CONTRIBUTING_COPY.rst +++ b/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/ , diff --git a/docs/source/index/citations.rst b/docs/source/index/citations.rst index 079bc7286..cc7d7052e 100755 --- a/docs/source/index/citations.rst +++ b/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 `__. + +**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 `__). 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 `__ always tracks the newest release +and `latest `__ the development branch.