Add version selector

.github/workflows/doc-build.yml

@@ -228,7 +228,7 @@ 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
           zip -r livedoc.zip livedoc
 
       - name: Upload live doc

src/bin/sage-update-version

@@ -112,6 +112,25 @@ export SAGE_VERSION
 export SAGE_RELEASE_DATE
 envsubst <"$SAGE_ROOT/CITATION.cff.in" >"$SAGE_ROOT/CITATION.cff"
 
+# Update src/doc/versions.txt file storing the URLs of the docs for the recent stable releases
+if [[ $SAGE_VERSION =~ ^[0-9]+(\.[0-9]+)*$ ]]; then
+    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
+fi
+
 # Commit auto-generated changes
 git commit -m "Updated SageMath version to $SAGE_VERSION" -- \
     "$SAGE_ROOT/VERSION.txt" \
@@ -124,6 +143,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

@@ -24,14 +24,51 @@ a.pdf:hover {
 /* Style for announcement banner */
 
 .announcement {
-    background: orange;
+  background: orange;
 }
 
 .announcement-content {
-    color: black;
+  color: black;
 }
 
 .announcement-content a {
+  color: white;
+  text-decoration: none;
+}
+
+/* Style for the floating versions menu */
+
+.sidebar-drawer {
+  z-index: 100;
+}
+
+#versions-menu {
+  position: fixed;
+  bottom: 10px;
+  right: 10px;
+  padding: 5px;
+  font-size: small;
+  opacity: 1;
+  background-color: white;
+  color: blue;
+}
+
+body[data-theme="dark"] {
+  #versions-menu {
+    background-color: black;
     color: white;
-    text-decoration: none;
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+  body[data-theme="auto"] {  /* the same styles with body[data-theme="dark"] */
+    #versions-menu {
+      background-color: black;
+      color: white;
+    }
+  }
+}
+
+#versions-menu:hover {
+    opacity: 1
 }

src/doc/common/static/custom-jupyter-sphinx.css

@@ -96,41 +96,41 @@ body[data-theme="dark"] {
 }
 
 @media (prefers-color-scheme: dark) {
- body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */
-  .jupyter_container {
-    color: white;
-    background-color: black;
-  }
-
-  .jupyter_container .highlight {
-    background-color: black;
-  }
-
-  .thebelab-button {
-    color: #d0d0d0;
-    background-color: #383838;
-  }
-
-  .thebelab-button:active {
-    color: #368ce2;
-  }
-
-  #thebelab-activate-button {
-    background-color: #383838;
-  }
-
-  #thebelab-activate-button:active {
-    color: #368ce2;
-  }
-
-  .thebelab-cell .jp-OutputArea-output {
-    color: white;
-    background-color: black;
-  }
-
-  .thebelab-cell .jp-OutputArea-output pre {
-    color: white;
-    background-color: black;
+  body[data-theme="auto"] { /* the same styles with body[data-theme="dark"] */
+    .jupyter_container {
+      color: white;
+      background-color: black;
+    }
+
+    .jupyter_container .highlight {
+      background-color: black;
+    }
+
+    .thebelab-button {
+      color: #d0d0d0;
+      background-color: #383838;
+    }
+
+    .thebelab-button:active {
+      color: #368ce2;
+    }
+
+    #thebelab-activate-button {
+      background-color: #383838;
+    }
+
+    #thebelab-activate-button:active {
+      color: #368ce2;
+    }
+
+    .thebelab-cell .jp-OutputArea-output {
+      color: white;
+      background-color: black;
+    }
+
+    .thebelab-cell .jp-OutputArea-output pre {
+      color: white;
+      background-color: black;
+    }
   }
- }
 }

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

@@ -58,6 +58,79 @@ const observer2 = new MutationObserver(callback);
 observer2.observe(document.getElementsByClassName("content")[0], { childList: true, subtree: true });
 
 
+//
+// Version selector
+//
+
+var versionMap = {};
+
+async function fetchVersions() {
+    try {
+        let versions_file = "https://raw.githubusercontent.com/sagemath/sage/develop/src/doc/versions.txt"
+        let response = await fetch(versions_file);
+        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) {
+                    if (!url.startsWith("https://")) {
+                        url = "https://" + url;
+                    }
+                    versionMap[ver] = url;
+                }
+            }
+        });
+    } catch (error) {
+        console.error("Failed to fetch versions.txt file:", error);
+    }
+
+    if (Object.keys(versionMap).length > 0) {
+        // Populate the versions menu
+        let dropdown = document.getElementById("versions-menu");
+        Object.keys(versionMap).forEach(ver => {
+            let option = document.createElement("option");
+            option.value = ver;
+            option.text = ver;
+            dropdown.add(option);
+        });
+    } else {
+        document.getElementById('versions-menu').style.display = 'none';
+    }
+
+    let urlParams = new URLSearchParams(window.location.search);
+    let version = urlParams.get("ver");
+    // Check if the version exists in the map and redirect
+    if (version in versionMap) {
+        let targetUrl = versionMap[version];
+        window.location.href = targetUrl + window.location.pathname;
+    } else {
+        console.error("Version not found in versions.txt.");
+    }
+}
+
+fetchVersions()
+
+// Function to change the version based on versions menu selection
+function changeVersion() {
+    let selectedVersion = document.getElementById("versions-menu").value;
+    if (selectedVersion) {
+       // Check if the version exists in the map and redirect
+        if (selectedVersion in versionMap) {
+            let targetUrl = versionMap[selectedVersion];
+            window.location.href = targetUrl + window.location.pathname;
+        } else {
+            console.error("Version not found in versions.txt.");
+        }
+    }
+}
+
+
 // Listen to the kernel status changes
 // https://thebe.readthedocs.io/en/stable/events.html
 thebelab.on("status", function (evt, data) {

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

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

src/doc/versions.txt

@@ -0,0 +1,17 @@
+# This file is used by the version selector of the sage doc
+# and updated by the script src/bin/sage-update-version
+# run by the release manager to prepare a new release
+#
+# The first line is reserved for develop version
+# The other lines are for recent stable releases (at most 5 lines)
+# A line consists of the version and the URL to the doc
+#
+# The sage-update-version script adds a new line for a new stable release
+#
+# Do not edit manually
+dev doc-release--sagemath.netlify.app
+10.4 doc-10-4--sagemath.netlify.app
+10.3 doc-10-3--sagemath.netlify.app
+10.2 doc-10-2--sagemath.netlify.app
+10.1 doc-10-1--sagemath.netlify.app
+10.0 doc-10-0--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

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",