Add version selector

.github/workflows/doc-build.yml

@@ -174,6 +174,7 @@ jobs:
           # We copy everything to a local folder
           docker cp --follow-link BUILD:/sage/local/share/doc/sage/html doc
           docker cp --follow-link BUILD:/sage/local/share/doc/sage/index.html doc
+          docker cp --follow-link BUILD:/sage/local/share/doc/sage/versions.txt doc
           (cd doc && git commit -a -m 'new')
           # Wipe out chronic diffs of new doc against old doc before creating CHANGES.html
           (cd doc && \
@@ -228,7 +229,8 @@ jobs:
           # We copy everything to a local folder
           docker cp --follow-link BUILD:/sage/local/share/doc/sage/html livedoc
           docker cp --follow-link BUILD:/sage/local/share/doc/sage/pdf livedoc
-          docker cp BUILD:/sage/local/share/doc/sage/index.html livedoc
+          docker cp --follow-link BUILD:/sage/local/share/doc/sage/index.html livedoc
+          docker cp --follow-link BUILD:/sage/local/share/doc/sage/versions.txt livedoc
           zip -r livedoc.zip livedoc
 
       - name: Upload live doc

src/bin/sage-update-version

@@ -112,6 +112,23 @@ export SAGE_VERSION
 export SAGE_RELEASE_DATE
 envsubst <"$SAGE_ROOT/CITATION.cff.in" >"$SAGE_ROOT/CITATION.cff"
 
+# Update versions.txt file storing URLs to the docs of the most recent stable releases
+file_path="$SAGE_ROOT/src/doc/versions.txt"
+# Extract the most recent version line from versions.txt; the first line is a comment
+line_number=$(grep -n '^[0-9]' "$file_path" | head -n 1 | cut -d: -f1)
+version_line=$(sed -n "${line_number}p" "$file_path")
+domain=${version_line#*--}
+version=${SAGE_VERSION//./-}
+# For the origin of this format, see .github/workflows/doc-publish.yml
+url="doc-$version--$domain"
+# Add new line to versions.txt
+sed -i "${line_number}i $SAGE_VERSION $url" "$file_path"
+# If the number of version lines is more than 5, remove the last line
+line_count=$(grep -c '^[0-9]' "$file_path")
+if [ "$line_count" -gt 5 ]; then
+  sed -i '$ d' "$file_path"
+fi
+
 # Commit auto-generated changes
 git commit -m "Updated SageMath version to $SAGE_VERSION" -- \
     "$SAGE_ROOT/VERSION.txt" \
@@ -124,6 +141,7 @@ git commit -m "Updated SageMath version to $SAGE_VERSION" -- \
     "$SAGE_ROOT/build/pkgs/*/version_requirements.txt" \
     "$SAGE_ROOT"/pkgs/*/VERSION.txt \
     "$SAGE_ROOT/.upstream.d/20-github.com-sagemath-sage-releases" \
+    "$SAGE_ROOT/src/doc/versions.txt" \
     || die "Error committing to the repository."
 
 git tag -a "$SAGE_VERSION" -m "$SAGE_VERSION_BANNER" \

src/doc/common/static/custom-furo.css

@@ -35,3 +35,22 @@ a.pdf:hover {
     color: white;
     text-decoration: none;
 }
+
+/* Style for the floating dropdown menu */
+
+#versionsMenu {
+    position: fixed;
+    bottom: 10px;
+    right: 10px;
+    padding: 5px;
+    font-size: 16px;
+    opacity: 1;
+}
+
+.sidebar-drawer {
+    z-index: 100;
+}
+
+#versionsMenu:hover {
+    opacity: 1
+}

src/doc/common/static/jupyter-sphinx-furo.js

@@ -58,6 +58,86 @@ const observer2 = new MutationObserver(callback);
 observer2.observe(document.getElementsByClassName("content")[0], { childList: true, subtree: true });
 
 
+//
+// Version selector
+//
+
+// Get query parameter by name
+function getQueryParam(param) {
+    let urlParams = new URLSearchParams(window.location.search);
+    return urlParams.get(param);
+}
+
+
+// Fetch the versions file and redirect based on the version parameter
+async function redirectToVersion() {
+    let version = getQueryParam("ver");
+    let versionMap = {};
+
+    try {
+        let response = await fetch('/versions.txt');
+        if (!response.ok) {
+            throw new Error('Network response was not ok');
+        }
+        let text = await response.text();
+        let lines = text.split('\n');
+
+        // Parse the versions.txt file
+        lines.forEach(line => {
+            if (!line.startsWith('#')) { // Ignore the comment line
+                let [ver, url] = line.split(' ');
+                if (ver && url) {
+                    versionMap[ver] = url;
+                }
+            }
+        });
+    } catch (error) {
+        console.error("Failed to fetch versions.txt:", error);
+    }
+
+    if (version) {
+        // Check if the version exists in the map and redirect
+        if (version in versionMap) {
+            let targetUrl = versionMap[version];
+
+            // Append "https://" if the URL does not start with "https://"
+            if (!targetUrl.startsWith("https://")) {
+                targetUrl = "https://" + targetUrl;
+            }
+            window.location.href = targetUrl + window.location.pathname;
+        } else {
+            console.error("Version not found in versions.txt.");
+        }
+    }
+
+    if (Object.keys(versionMap).length > 0) {
+        // Populate the versions menu
+        let dropdown = document.getElementById("versionsMenu");
+        Object.keys(versionMap).forEach(ver => {
+            let option = document.createElement("option");
+            option.value = ver;
+            option.text = ver;
+            dropdown.add(option);
+        });
+    } else {
+        document.getElementById('versionsMenu').style.display = 'none';
+    }
+}
+
+// Redirect if query parameter "ver" is given
+redirectToVersion();
+
+// Function to change the version based on versions menu selection
+function changeVersion() {
+    let selectedVersion = document.getElementById("versionsMenu").value;
+    if (selectedVersion) {
+        let currentUrl = new URL(window.location);
+        currentUrl.searchParams.set("ver", selectedVersion);
+        window.location.href = currentUrl.toString();
+    }
+}
+
+
 // Listen to the kernel status changes
 // https://thebe.readthedocs.io/en/stable/events.html
 thebelab.on("status", function (evt, data) {
@@ -126,3 +206,6 @@ document.querySelectorAll('input[class="tab-input"]').forEach((elem) => {
         }
     });
 });
+
+
+

src/doc/common/templates-furo/sidebar/version-selector.html

@@ -0,0 +1,3 @@
+<select id="versionsMenu" onchange="changeVersion()">
+    <option value="">Versions</option>
+</select>

src/doc/versions.txt

@@ -0,0 +1,4 @@
+# This file is maintained by src/bin/sage-update-version script.
+dev doc-release--sagemath.netlify.app
+10.3 doc-10-3--sagemath.netlify.app
+10.2 doc-10-2--sagemath.netlify.app

src/sage_docbuild/builders.py

@@ -76,7 +76,7 @@
 import sage.all
 from sage.misc.cachefunc import cached_method
 # Do not import SAGE_DOC globally as it interferes with doctesting with a random replacement
-from sage.env import SAGE_DOC_SRC, SAGE_SRC, DOT_SAGE
+from sage.env import SAGE_DOC, SAGE_DOC_SRC, SAGE_SRC, DOT_SAGE
 from . import build_options
 from .utils import build_many as _build_many
 
@@ -214,7 +214,6 @@ def _output_dir(self, type):
             sage: b._output_dir('html')         # optional - sagemath_doc_html
             '.../html/en/tutorial'
         """
-        from sage.env import SAGE_DOC
         d = os.path.join(SAGE_DOC, type, self.lang, self.name)
         os.makedirs(d, exist_ok=True)
         return d
@@ -455,6 +454,9 @@ def html(self):
         shutil.copy2(os.path.join(SAGE_DOC_SRC, self.lang, 'website', 'root_index.html'),
                      root_index_file)
 
+        versions_file = os.path.join(SAGE_DOC, 'versions.txt')
+        shutil.copy2(os.path.join(SAGE_DOC_SRC, 'versions.txt'), versions_file)
+
     def pdf(self):
         """
         Build the website hosting pdf docs.

src/sage_docbuild/conf.py

@@ -474,6 +474,7 @@ def linkcode_resolve(domain, info):
         "sidebar/scroll-start.html",
         "sidebar/brand.html",
         "sidebar/search.html",
+        "sidebar/version-selector.html",
         "sidebar/home.html",
         "sidebar/navigation.html",
         "sidebar/ethical-ads.html",