ENH: Version dropdown redirection.

docs/_static/switcher.json

@@ -1,4 +1,7 @@
-[
+{
+  "preferred_version": "stable",
+  "development_version": "latest",
+  "entries": [
   {
     "name": "dev",
     "version": "latest",
@@ -54,4 +57,5 @@
     "version": "v0.3.2",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.3.2/"
   }
-]
+],
+}

docs/user_guide/version-dropdown.rst

@@ -31,43 +31,52 @@ 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 can have the following fields:
+First, create a JSON file stating which versions of your docs will be listed in
+the switcher's dropdown menu.
+The contents of this file are a **dictionary** of key-val pairs that configure the version switcher.
+
+The only required key of this configuration is called ``entries``.
+It corresponds to a list of entries for each version of the documentation you wish to include.
+
+Each item in ``entries`` may have the following fields:
 
 - ``version``: a version string. This is checked against
   ``switcher['version_match']`` to provide styling to the switcher.
 - ``url``: the URL for this version.
 - ``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",
-            "url": "https://mysite.org/en/2.1/index.html"
-        },
-        {
-            "version": "2.1rc1",
-            "url": "https://mysite.org/en/2.1rc1/index.html"
-        },
-        {
-            "version": "2.0",
-            "url": "https://mysite.org/en/2.0/index.html"
-        },
-        {
-            "version": "1.0",
-            "url": "https://mysite.org/en/1.0/index.html"
-        }
-    ]
+Here is an example JSON file that adds a list of several version entries.
+
+.. code-block:: json
+    :caption: switcher.json
+
+    {
+        "entries":[
+            {
+                "name":"v2.1 (stable)",
+                "version":"2.1",
+                "url":"https://mysite.org/en/2.1/index.html"
+            },
+            {
+                "version":"2.2rc1",
+                "url":"https://mysite.org/en/2.2rc1/index.html"
+            },
+            {
+                "version":"2.0",
+                "url":"https://mysite.org/en/2.0/index.html"
+            },
+            {
+                "version":"1.0",
+                "url":"https://mysite.org/en/1.0/index.html"
+            }
+        ]
+    }
 
-See the discussion of ``switcher['json_url']`` (below) for options of where to
-save the JSON file.
+In addition to ``entries`` there are a few other key/value configuration options, as explained below.
+See :ref:`switcher-url-location` for options of where to save the JSON file.
 
+.. _switcher-url-location:
 
 Configure ``switcher['json_url']``
 ----------------------------------
@@ -222,3 +231,76 @@ version, you could use the following CSS selector:
 
    See the `MDN documentation on dataset properties <https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset>`_
    for more information on using and styling with these properties.
+
+
+Add a warning banner to direct users to a specific version
+----------------------------------------------------------
+
+You can add a large warning banner to direct users to a specific version of your documentation if they are on a different version.
+This is useful if you have many versions of your documentation (e.g. old releases, development versions) and wish to direct users to a specific version (e.g., the latest stable version).
+
+To activate this feature, use the ``preferred_version`` key in your ``versions.json`` configuration file.
+The value should be the unique identifier of the version to which users should be redirected.
+
+For example, below we modify the ``switcher.json`` file described above to note version ``2.1`` as the preferred version.
+
+.. code-block:: json
+    :caption: switcher.json
+
+    {
+       "preferred_version":"2.1",
+       "entries":[
+          {
+             "name":"v2.1 (stable)",
+             "version":"2.1",
+             "url":"https://mysite.org/en/2.1/index.html"
+          },
+          {
+             "version":"2.2rc1",
+             "url":"https://mysite.org/en/2.2rc1/index.html"
+          },
+          {
+             "version":"2.0",
+             "url":"https://mysite.org/en/2.0/index.html"
+          },
+          {
+             "version":"1.0",
+             "url":"https://mysite.org/en/1.0/index.html"
+          }
+       ],
+    }
+
+For all documentation pages on a different version, a large warning banner will be displayed stating that they they are on an out-of-date version, with a button to direct them to the preferred version.
+
+Specify that an outdated version is a *development* version
+```````````````````````````````````````````````````````````
+
+If a version is a "development" version instead of an out-dated version, you may change the message that is displayed.
+To do so, add a ``development_version`` key to your JSON configuration, like so:
+
+.. code-block:: json
+    :caption: switcher.json
+
+    {
+       "preferred_version":"2.1",
+       "development_version":"2.2rc1",
+       "entries":[
+          {
+             "name":"v2.1 (stable)",
+             "version":"2.2rc1",
+             "url":"https://mysite.org/en/2.1/index.html"
+          },
+          {
+             "version":"2.2rc1",
+             "url":"https://mysite.org/en/2.2rc1/index.html"
+          },
+          {
+             "version":"2.0",
+             "url":"https://mysite.org/en/2.0/index.html"
+          },
+          {
+             "version":"1.0",
+             "url":"https://mysite.org/en/1.0/index.html"
+          }
+       ],
+    }

src/pydata_sphinx_theme/__init__.py

@@ -18,7 +18,7 @@
 
 from .bootstrap_html_translator import BootstrapHTML5Translator
 
-__version__ = "0.10.1"
+__version__ = "0.10.1dev0"
 
 logger = logging.getLogger(__name__)
 

src/pydata_sphinx_theme/assets/scripts/index.js

@@ -303,8 +303,15 @@ if (themeSwitchBtns) {
         btn.dataset["activeVersionName"] = "";
         btn.dataset["activeVersion"] = "";
       });
+
+      // If data is a list, turn it into a dictionary with an `entries` field
+      if (data.isArray()) {
+        data = {"entries": data};
+        console.log("[PST]: Version switcher entries were a list. Moving to `entries` key.")
+      }
+
       // create links to the corresponding page in the other docs versions
-      $.each(data, function (index, entry) {
+      $.each(data["entries"], function (index, entry) {
         // if no custom name specified (e.g., "latest"), use version string
         if (!("name" in entry)) {
           entry.name = entry.version;
@@ -345,7 +352,35 @@ if (themeSwitchBtns) {
             btn.dataset["activeVersion"] = entry.version;
           });
         }
+
+        // If a preferred_version is specified and it is this entry, store the
+        // entry's information to use later.
+        if (entry.version === data["preferred_version"]) {
+          var preferred_version = entry.version;
+        }
       });
+
+      // If this is a preferred version, display a banner to redirect to it.
+      if ((preferred_version) && (preferred_version != btn.dataset["activeVersion"])) {
+        // Specify whether we are on an old version or a development version
+        if ((data["development_version"]) && (data["development_version"] == btn.dataset["activeVersion"])) {
+          var redirect_msg = "This a <strong>development version</strong> of the documentation."
+        } else {
+          var redirect_msg = "This is an <strong>outdated version</strong> of the documentation."
+        };
+
+        // Replace our warning banner placeholder with a visible banner
+        placeholder = document.getElementById("header-version-warning-placeholder");
+        placeholder.insertAdjacentHTML("afterend", `
+        <div class="bd-header-version-warning container-fluid" id="header-version-warning">
+            <div class="bd-header-version-warning__content">
+                <span>${redirect_msg}</span>
+                <a href="${preferred_version.url}${currentFilePath}"><button class="btn">Switch to: ${preferred_version.name}</button></a>
+            </div>
+        </div>
+        `);
+        console.log("[PST]: Inserted version warning banner...");
+      }
     }
   );
 }

src/pydata_sphinx_theme/assets/styles/index.scss

@@ -40,6 +40,7 @@ $grid-breakpoints: (
 @import "./sections/footer-article";
 @import "./sections/header";
 @import "./sections/header-article";
+@import "./sections/header-version-warning";
 @import "./sections/sidebar-primary";
 @import "./sections/sidebar-secondary";
 @import "./sections/sidebar-toggle";

src/pydata_sphinx_theme/assets/styles/sections/header-version-warning.scss

@@ -0,0 +1,34 @@
+/**
+ * A warning banner to direct users to a stable version of the documentation.
+ */
+ .bd-header-version-warning {
+  position: relative; // So the background color variable fill works
+  padding: 1rem;
+
+  .bd-header-version-warning__content {
+    @include background-from-color-variable(--pst-color-danger, 0.2);
+    display: flex;
+    justify-content: center;
+    align-content: center;
+    gap: 1rem;
+    font-size: 1.2rem;
+
+    span {
+      margin: auto 0;
+      text-align: center;
+    }
+
+    // The button to the right of the banner text.
+    a {
+      z-index: 1; // To put it above the background banner.
+      button {
+        font-size: 1.2rem;
+        background-color: var(--pst-color-danger);
+        color: var(--pst-color-on-background);
+        &:active {
+          opacity: 0.8;
+        }
+      }
+    }
+  }
+}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -78,6 +78,10 @@
   </nav>
   {% endblock %}
 
+  {# Versoin warning placeholder that is replaced by the switcher JS #}
+  {% include "sections/version-warning.html" %}
+
+  {# Main container for site content sections #}
   <div class="bd-container">
     <div class="bd-container__inner bd-page-width">
       {# Primary sidebar #}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/version-warning.html

@@ -0,0 +1,6 @@
+{# A placeholder for a version warning that will be replaced with a banner #}
+{# ref: components/version-switcher.html for JS that does this #}
+{%- if theme_switcher %}
+<!-- A placeholder we use to insert a version warning banner if a preferred version is specified. -->
+<div id="header-version-warning-placeholder"></div>
+{% endif -%}