Add a version selector to the sidebar

This requires a versions.json file to be placed at the root of the SymPy docs
repo like

{
    "latest": "1.10",
    "dev": "1.11.dev"
}

doc/src/_static/custom.css

@@ -26,6 +26,22 @@ blockquote {
     margin-block-end: -0.5rem;
 }
 
+/* Version selector. See _templates/sidebar/versions.html */
+.versions-header {
+    color: white;
+    padding: var(--sidebar-item-spacing-vertical) var
+             (--sidebar-item-spacing-horizontal);
+    margin: 1rem 0rem;
+}
+.current-version {
+    background-color: #2f431e;
+}
+.versions-not-found {
+    color: white;
+    font-style: italic;
+    padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);
+}
+
 /* Make the "SymPy documentation" text bold */
 .sidebar-brand-text {
     font-weight: bold;

doc/src/_templates/sidebar/versions.html

@@ -0,0 +1,56 @@
+<!-- Versions Menu. In order to work, there should be a file called versions.json one level up from the documentation listing the "dev" and "latest" version numbers, like
+{
+    "latest": "1.10",
+    "dev": "1.11.dev"
+}
+-->
+<div class="sidebar-tree sidebar-versions">
+  <h5 class="versions-header">Documentation Version</h4>
+</div>
+
+<!-- Make sure jquery is loaded (we would put this as a separate .js, but it uses jinja templates in some of the variables) -->
+<script src="{{ pathto('_static/jquery.js', 1) }}"></script>
+<script>
+  var json_loc = "../{{ pathto('versions.json', 1) }}";
+
+  function add_version_menu(json_loc) {
+      var menu = document.createElement("ul");
+      var thisversion = "{{ 'dev' if '.dev' in release else 'latest' }}"
+      $.getJSON(json_loc, {"crossDomain": true}, function(versions) {
+          for (var key in versions) {
+              if (key != "latest" && key != "dev") {
+                  console.error("Invalid key in versions.json", key);
+              } else {
+                  var version = document.createElement("li")
+                  version.className = "sidebar-versions-l1 sidebar-versions-" + key + "-l1";
+                  if (key == thisversion){
+                      version.className += " current-version";
+                  }
+                  var a = document.createElement("a");
+                  a.className = "reference internal";
+                  a.innerHTML = "SymPy " + versions[key] + " (" + key + " version)";
+                  a.title = key + " version";
+                  a.href = "https://docs.sympy.org/" + key + "/{{ pagename }}.html";
+                  version.appendChild(a);
+                  menu.appendChild(version);
+              }
+          }
+      }).done(function() {
+          console.log("versions.json read successfully");
+      }).fail(function() {
+          var version = document.createElement("li")
+          version.className = "sidebar-versions-l1 sidebar-versions-latest-l1";
+          var d = document.createElement("div");
+          d.className = "versions-not-found"
+          d.innerHTML = "Other Versions Not Found";
+          d.title = "The version selection menu is only available for the documentation published on docs.sympy.org";
+          version.appendChild(d);
+          menu.appendChild(version);
+          console.error("Could not read versions.json");
+      }).always(function() {
+          $(".sidebar-versions").append(menu)
+      });
+  };
+
+  $( document ).ready( add_version_menu(json_loc));
+</script>

doc/src/conf.py

@@ -152,6 +152,7 @@
         "sidebar/brand.html",
         "sidebar/search.html",
         "sidebar/navigation.html",
+        "sidebar/versions.html",
         "sidebar/scroll-end.html",
     ],
 }
@@ -230,6 +231,8 @@
 # aren't specified in the Furo theme as CSS variables
 html_css_files = ['custom.css']
 
+# html_js_files = []
+
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
@@ -249,7 +252,7 @@
 html_domain_indices = ['py-modindex']
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
-#html_copy_source = True
+# html_copy_source = True
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'SymPydoc'