✨ NEW: add version switcher

docs/_static/switcher.json

@@ -0,0 +1,51 @@
+[
+    {
+        "name": "v0.7.1 (stable)",
+        "version": "0.7.1"
+    },
+    {
+        "version": "0.7.0"
+    },
+    {
+        "version": "0.6.3"
+    },
+    {
+        "version": "0.6.2"
+    },
+    {
+        "version": "0.6.1"
+    },
+    {
+        "version": "0.6.0"
+    },
+    {
+        "version": "0.5.2"
+    },
+    {
+        "version": "0.5.1"
+    },
+    {
+        "version": "0.5.0"
+    },
+    {
+        "version": "0.4.3"
+    },
+    {
+        "version": "0.4.2"
+    },
+    {
+        "version": "0.4.1"
+    },
+    {
+        "version": "0.4.0"
+    },
+    {
+        "version": "0.3.2"
+    },
+    {
+        "version": "0.3.1"
+    },
+    {
+        "version": "0.3.0"
+    }
+]

docs/conf.py

@@ -24,7 +24,8 @@
 
 import pydata_sphinx_theme
 
-version = pydata_sphinx_theme.__version__.replace("dev0", "")
+release = pydata_sphinx_theme.__version__
+version = release.replace("dev0", "")
 
 # -- General configuration ---------------------------------------------------
 
@@ -96,8 +97,14 @@
     # "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": ["version-switcher", "navbar-icon-links"],
     # "footer_items": ["copyright", "sphinx-version", ""]
+    "switcher": {
+        "json_url": "/_static/switcher.json",
+        # "json_url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/_static/switcher.json",
+        "url_template": "https://pydata-sphinx-theme.readthedocs.io/en/v{version}/",
+        "version_match": version,
+    },
 }
 
 

docs/user_guide/configuring.rst

@@ -277,6 +277,198 @@ at the bottom. You can hide these buttons with the following configuration:
    }
 
 
+Add a dropdown to switch between docs versions
+==============================================
+
+You can add a button to your site that allows users to
+switch between versions of your documentation. The links in the version
+switcher will differ depending on which page of the docs is being viewed. For
+example, on the page ``https://mysite.org/en/v2.0/changelog.html``, the
+switcher links will go to ``changelog.html`` in the other versions of your
+docs. When clicked, the switcher will check for the existence of that page, and
+if it doesn't exist, redirect to the homepage of that docs version instead.
+
+The switcher requires the following configuration steps:
+
+1. Add a JSON file containing a list of the documentation versions that the
+   switcher should show on each page.
+
+2. Add a configuration dictionary called ``switcher`` to the
+   ``html_theme_options`` dict in ``conf.py``. ``switcher`` should have 3 keys:
+
+   - ``json_url``: the persistent location of the JSON file described above.
+   - ``url_template``: a template string used to generate the correct URLs for
+     the different documentation versions.
+   - ``version_match``: a string stating the version of the documentation that
+     is currently being browsed.
+
+3. Specify where to place the switcher in your page layout. For example, add
+   the ``"version-switcher"`` template to one of the layout lists in
+   ``html_theme_options`` (e.g., ``navbar_end``, ``footer_items``, etc).
+
+Below is a more in-depth description of each of these configuration steps.
+
+
+Add a JSON file to define your switcher's versions
+--------------------------------------------------
+
+First, write a JSON file stating which versions of your docs will be listed in
+the switcher's dropdown menu. That file should contain a list of entries that
+each have one or two fields:
+
+- ``version``: a version string. This will be inserted into
+  ``switcher['url_template']`` to create the links to other docs versions, and
+  also checked against ``switcher['version_match']`` to provide styling to the
+  switcher.
+- ``name``: an optional name to display in the switcher dropdown instead of the
+  version string (e.g., "latest", "stable", "dev", etc).
+
+Here is an example JSON file:
+
+.. code:: json
+
+    [
+        {
+            "name": "v2.1 (stable)",
+            "version": "2.1"
+        },
+        {
+            "version": "2.0"
+        },
+        {
+            "version": "1.0"
+        },
+    ]
+
+See the discussion of ``switcher['json_url']`` (below) for options of where to
+save the JSON file.
+
+
+Configure ``switcher['json_url']``
+----------------------------------
+
+The JSON file needs to be at a stable, persistent, fully-resolved URL (i.e.,
+not specified as a path relative to the sphinx root of the current doc build).
+Each version of your documentation should point to the same URL, so that as new
+versions are added to the JSON file all the older versions of the docs will
+gain switcher dropdown entries linking to the new versions. This could be done
+a few different ways:
+
+- The location could be one that is always associated with the most recent
+  documentation build (i.e., if your docs server aliases "latest" to the most
+  recent version, it could point to a location in the build tree of version
+  "latest"). For example:
+
+  .. code:: python
+
+      html_theme_options = {
+          ...,
+          "switcher": {
+              "json_url": "https://mysite.org/en/latest/_static/switcher.json",
+          }
+      }
+
+  In this case the JSON is versioned alongside the rest of the docs pages but
+  only the most recent version is ever loaded (even by older versions of the
+  docs).
+
+- The JSON could be saved in a folder that is listed under your site's
+  ``html_static_path`` configuration. See `the Sphinx static path documentation
+  <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path>`_
+  for more information.
+
+- The JSON could be stored outside the doc build trees. This probably means it
+  would be outside the software repo, and would require you to add new version
+  entries to the JSON file manually as part of your release process. Example:
+
+  .. code:: python
+
+      html_theme_options = {
+          ...,
+          "switcher": {
+              "json_url": "https://mysite.org/switcher.json",
+          }
+      }
+
+
+Configure ``switcher['url_template']``
+--------------------------------------
+
+The switcher's links to other versions of your docs are made by combining the
+*version strings* from the JSON file with a *template string* you provide in
+``switcher['url_template']``. The template string must contain a placeholder
+``{version}`` and otherwise be a fully-resolved URL. For example:
+
+.. code:: python
+
+    html_theme_options = {
+        ...,
+        "switcher": {
+            "url_template": "https://mysite.org/en/version-{version}/",
+        }
+    }
+
+The example above will result in a link to
+``https://mysite.org/en/version-1.0/`` for the JSON entry for version
+``"1.0"``.
+
+
+Configure ``switcher['version_match']``
+---------------------------------------
+
+This configuration value tells the switcher what docs version is currently
+being viewed, and is used to style the switcher (i.e., to highlight the current
+docs version in the switcher's dropdown menu, and to change the text displayed
+on the switcher button).
+
+Typically you can re-use one of the sphinx variables ``version``
+or ``release`` as the value of ``switcher['version_match']``; which one you use
+depends on how granular your docs versioning is. See
+`the Sphinx "project info" documentation
+<https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information>`__
+for more information). Example:
+
+.. code:: python
+
+    version = my_package_name.__version__.replace("dev0", "")  # may differ
+    html_theme_options = {
+        ...,
+        "switcher": {
+            "version_match": version,
+        }
+    }
+
+
+Specify where to display the switcher
+-------------------------------------
+
+Finally, tell the theme where on your site's pages you want the switcher to
+appear. There are many choices here: you can add ``"version-switcher"`` to one
+of the locations in ``html_theme_options`` (e.g., ``navbar_end``,
+``footer_items``, etc). For example:
+
+.. code:: python
+
+   html_theme_options = {
+      ...,
+      "navbar_end": ["version-switcher"]
+   }
+
+
+Alternatively, you could override one of the other templates to include the
+version switcher in a sidebar. For example, you could define
+``_templates/sidebar-nav-bs.html`` as:
+
+.. code:: jinja
+
+    {%- include 'version-switcher.html' -%}
+    {{ super() }}
+
+to insert a version switcher at the top of the left sidebar, while still
+keeping the default navigation below it. See :doc:`sections` for more
+information.
+
+
 Add an Edit this Page button
 ============================
 

docs/user_guide/sections.rst

@@ -11,7 +11,7 @@ You can choose which templates show up in each section, as well as the order in
 which they appear. This page describes the major areas that you can customize.
 
 .. note::
-    
+
    When configuring templates in each section, you may omit the ``.html``
    suffix after each template if you wish.
 
@@ -118,6 +118,7 @@ will be named accordingly).
 - ``sidebar-ethical-ads.html``
 - ``sidebar-nav-bs.html``
 - ``sphinx-version.html``
+- ``version-switcher.html``
 
 Add your own HTML templates to theme sections
 =============================================
@@ -136,7 +137,7 @@ could do so with the following steps:
       {{ version }}
 
 1. Now add the file to your menu items for one of the sections above. For example:
-   
+
    .. code-block:: python
 
       html_theme_options = {

pydata_sphinx_theme/_templates/version-switcher.html

@@ -0,0 +1,79 @@
+<div class="dropdown" id="version_switcher">
+    <button type="button" class="btn btn-primary btn-sm navbar-btn dropdown-toggle" id="version_switcher_button" data-toggle="dropdown">
+        {{ theme_switcher.get('version_match') }}  <!-- this text may get changed later by javascript -->
+        <span class="caret"></span>
+    </button>
+    <div id="version_switcher_menu" class="dropdown-menu list-group-flush py-0" aria-labelledby="version_switcher_button">
+    <!-- dropdown will be populated by javascript on page load -->
+    </div>
+</div>
+
+<!-- NOTE: this JS must live here (not in our global JS file) because it relies
+     on being processed by Jinja before it is run (specifically for replacing
+     variables {{ pagename }} and {{ theme_switcher }}.
+-->
+
+<script type="text/javascript">
+// Construct the target URL from the JSON components
+function buildURL(entry) {
+    var template = "{{ theme_switcher.get('url_template') }}";  // supplied by jinja
+    template = template.replace("{version}", entry.version);
+    return template;
+}
+
+// Check if corresponding page path exists in other version of docs
+// and, if so, go there instead of the homepage of the other docs version
+function checkPageExistsAndRedirect(event) {
+    const currentFilePath = "{{ pagename }}.html",
+          tryUrl = event.target.getAttribute("href");
+    let otherDocsHomepage = tryUrl.replace(currentFilePath, "");
+    $.ajax({
+        type: 'HEAD',
+        url: tryUrl,
+        // if the page exists, go there
+        success: function() {
+            location.href = tryUrl;
+        }
+    }).fail(function() {
+        location.href = otherDocsHomepage;
+    });
+    // this prevents the browser from following the href of the clicked node
+    // (which is fine because this function takes care of redirecting)
+    return false;
+}
+
+// Populate the version switcher from the JSON config file
+(function () {
+    $.getJSON("{{ theme_switcher.get('json_url') }}", function(data, textStatus, jqXHR) {
+        const currentFilePath = "{{ pagename }}.html";
+        // create links to the corresponding page in the other docs versions
+        $.each(data, function(index, entry) {
+            // if no custom name specified (e.g., "latest"), use version string
+            if (!("name" in entry)) {
+                entry.name = entry.version;
+            }
+            // create the node
+            const node = document.createElement("a");
+            node.setAttribute("class", "list-group-item list-group-item-action py-1");
+            node.textContent = `${entry.name}`;
+            // get the base URL for that doc version, add the current page's
+            // path to it, and set as `href`
+            entry.url = buildURL(entry);
+            node.setAttribute("href", `${entry.url}${currentFilePath}`);
+            // on click, AJAX calls will check if the linked page exists before
+            // trying to redirect, and if not, will redirect to the homepage
+            // for that version of the docs.
+            node.onclick = checkPageExistsAndRedirect;
+            $("#version_switcher_menu").append(node);
+            // replace dropdown button text with the preferred display name of
+            // this version, rather than using sphinx's {{ version }} variable.
+            // also highlight the dropdown entry for the currently-viewed
+            // version's entry
+            if (entry.version == "{{ theme_switcher.get('version_match') }}") {
+                node.classList.add("active");
+                $("#version_switcher_button").text(entry.name);
+            }
+        });
+    });
+})();
+</script>

pydata_sphinx_theme/theme.conf

@@ -31,4 +31,5 @@ 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 =