From 4614ce2899dea83381972d090843389fe4009bf2 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Mon, 16 Nov 2026 09:44:49 -0600 Subject: [PATCH] Sort tutorial versions by release date Signed-off-by: Alec Scott --- .readthedocs.yaml | 1 + _static/js/versions.js | 5 ++++- _templates/base.html | 1 + conf.py | 17 +++++++++++++++++ 4 files changed, 23 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4332acf6ea..e129c4d97f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -18,6 +18,7 @@ build: jobs: post_checkout: - git fetch --unshallow || true # get accurate "Last updated on" info + - git fetch origin '+refs/heads/*:refs/remotes/origin/*' '+refs/tags/*:refs/tags/*' || true # date all versions for the picker # Build documentation in the "docs/" directory with Sphinx sphinx: diff --git a/_static/js/versions.js b/_static/js/versions.js index 67711d95e9..bb3f379ac6 100644 --- a/_static/js/versions.js +++ b/_static/js/versions.js @@ -12,7 +12,10 @@ document.addEventListener("readthedocs-addons-data-ready", function (event) { const versionSwitch = document.querySelector( "div.version-switch", ); - let versions = config.versions.active; + // newest first; tags are keyed by name, branches by branch name. + // Unknown refs (created after this build) are assumed newest. + const date = (v) => VERSION_DATES[v.type === "tag" ? v.slug : v.identifier] ?? Number.MAX_SAFE_INTEGER; + const versions = config.versions.active.sort((a, b) => date(b) - date(a)); if (config.versions.current.hidden || config.versions.current.type === "external") { versions.unshift(config.versions.current); } diff --git a/_templates/base.html b/_templates/base.html index d288e285ec..b04bd9cecc 100644 --- a/_templates/base.html +++ b/_templates/base.html @@ -11,6 +11,7 @@ {%- if READTHEDOCS %} + {%- endif %} {% endblock %} diff --git a/conf.py b/conf.py index 0fb3a066e0..93742393d5 100644 --- a/conf.py +++ b/conf.py @@ -16,6 +16,7 @@ # serve to show the default. import os +import subprocess import sys from pygments.formatters.html import HtmlFormatter @@ -287,6 +288,22 @@ def setup(sphinx): if os.environ.get("READTHEDOCS", "") == "True": html_context["READTHEDOCS"] = True + # Ref dates, used by _static/js/versions.js to sort the version picker by date + refs = subprocess.run( + [ + "git", + "for-each-ref", + "--format=%(refname) %(creatordate:unix)", + "refs/remotes/origin", + "refs/tags", + ], + capture_output=True, + text=True, + ).stdout + html_context["version_dates"] = { + ref.removeprefix("refs/tags/").removeprefix("refs/remotes/origin/"): int(date) + for ref, date in map(str.split, refs.splitlines()) + } # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format.