add version switcher (cleaner diff this time)

pydata · Aug 10, 2021 · b261510 · b261510
1 parent 8dc3d93
commit b261510
Show file tree

Hide file tree

Showing 4 changed files with 155 additions and 3 deletions.
diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json
@@ -0,0 +1,97 @@
+[
+    {
+        "name": "v0.6.3 (latest)",
+        "version": "latest",
+        "language": "en"
+    },
+    {
+        "name": "v0.6.2",
+        "version": "v0.6.2",
+        "language": "en"
+    },
+    {
+        "name": "v0.6.1",
+        "version": "v0.6.1",
+        "language": "en"
+    },
+    {
+        "name": "v0.6.0",
+        "version": "v0.6.0",
+        "language": "en"
+    },
+    {
+        "name": "v0.5.2",
+        "version": "v0.5.2",
+        "language": "en"
+    },
+    {
+        "name": "v0.5.1",
+        "version": "v0.5.1",
+        "language": "en"
+    },
+    {
+        "name": "v0.5.0",
+        "version": "v0.5.0",
+        "language": "en"
+    },
+    {
+        "name": "v0.4.3",
+        "version": "v0.4.3",
+        "language": "en"
+    },
+    {
+        "name": "v0.4.2",
+        "version": "v0.4.2",
+        "language": "en"
+    },
+    {
+        "name": "v0.4.1",
+        "version": "v0.4.1",
+        "language": "en"
+    },
+    {
+        "name": "v0.4.0",
+        "version": "v0.4.0",
+        "language": "en"
+    },
+    {
+        "name": "v0.3.2",
+        "version": "v0.3.2",
+        "language": "en"
+    },
+    {
+        "name": "v0.3.1",
+        "version": "v0.3.1",
+        "language": "en"
+    },
+    {
+        "name": "v0.3.0",
+        "version": "v0.3.0",
+        "language": "en"
+    },
+    {
+        "name": "v0.2.2",
+        "version": "v0.2.2",
+        "language": "en"
+    },
+    {
+        "name": "v0.2.1",
+        "version": "v0.2.1",
+        "language": "en"
+    },
+    {
+        "name": "v0.2.0",
+        "version": "v0.2.0",
+        "language": "en"
+    },
+    {
+        "name": "v0.1.1",
+        "version": "v0.1.1",
+        "language": "en"
+    },
+    {
+        "name": "v0.1.0",
+        "version": "v0.1.0",
+        "language": "en"
+    }
+]
diff --git a/docs/conf.py b/docs/conf.py
@@ -23,7 +23,8 @@
 
 import pydata_sphinx_theme
 
-version = pydata_sphinx_theme.__version__.replace("dev0", "")
+release = pydata_sphinx_theme.__version__
+version = release.replace("dev0", "")
 
 # -- General configuration ---------------------------------------------------
 
@@ -81,7 +82,7 @@
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     # "navbar_start": ["navbar-logo", "navbar-version"],
     # "navbar_center": ["navbar-nav", "navbar-version"],  # Just for testing
-    # "navbar_end": ["navbar-icon-links", "navbar-version"]  # Just for testing
+    "navbar_end": ["switcher", "navbar-icon-links"],
     # "footer_items": ["copyright", "sphinx-version", ""]
 }
 
@@ -91,6 +92,8 @@
     "github_repo": "pydata-sphinx-theme",
     "github_version": "master",
     "doc_path": "docs",
+    "switcher_json_url": "/_static/switcher.json",
+    "switcher_template_url": "https://pydata-sphinx-theme.readthedocs.io/{language}/{version}/",
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/pydata_sphinx_theme/_templates/switcher.html b/pydata_sphinx_theme/_templates/switcher.html
@@ -0,0 +1,50 @@
+<div class="dropdown">
+    <button type="button" class="btn btn-primary btn-sm navbar-btn dropdown-toggle" id="switcher_button" data-toggle="dropdown">
+        {{ switcher_prefix }}{{ release }}
+        <span class="caret"></span>
+    </button>
+    <div id="switcher" class="dropdown-menu list-group-flush py-0" aria-labelledby="switcher_button">
+    <!-- dropdown will be populated by javascript on page load -->
+    </div>
+</div>
+
+<script type="text/javascript">
+// Function to construct the target URL from the JSON components
+function buildURL(template, entry) {
+    //
+    var parts = template.split(/[\{\}]/);
+    version_ix = parts.indexOf("version");
+    language_ix = parts.indexOf("language");
+    if (version_ix >= 0) {
+        parts[version_ix] = entry.version;
+    }
+    if (language_ix >= 0) {
+        parts[language_ix] = entry.language;
+    }
+    return parts.join("");
+}
+// Function to populate the (release, language) version switcher
+(function () {
+    // get JSON config
+    $.getJSON("{{ switcher_json_url }}", function(data, textStatus, jqXHR) {
+        // create the nodes first (before AJAX calls) to ensure the order is
+        // correct (for now, links will go to doc version homepage)
+        $.each(data, function(index, entry) {
+            entry.url = buildURL("{{ switcher_template_url }}", entry);
+            $("#switcher").append(`<a class="list-group-item list-group-item-action py-1" href="${entry.url}">${entry.name}</a>`);
+        });
+        // see if the current page exists in the other versions of the docs
+        $.each(data, function(index, entry) {
+            let filePath = "{{ pagename }}.html";
+            $.ajax({
+                type: 'HEAD',
+                url: `${entry.url}${filePath}`,
+                // update the target URL if it exists
+                success: function() {
+                    $("#switcher").children()[index].setAttribute("href", `${entry.url}${filePath}`);
+                }
+            });
+        });
+    });
+})();
+</script>
diff --git a/pydata_sphinx_theme/theme.conf b/pydata_sphinx_theme/theme.conf
@@ -29,4 +29,6 @@ navbar_start = navbar-logo.html
 navbar_center = navbar-nav.html
 navbar_end = navbar-icon-links.html
 footer_items = copyright.html, sphinx-version.html
-page_sidebar_items = page-toc.html, edit-this-page.html
+page_sidebar_items = page-toc.html, edit-this-page.html
+switcher_json_url =
+switcher_template_url =