ENH: Add version warning bar

docs/conf.py

@@ -167,6 +167,7 @@
     "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     "navbar_center": ["version-switcher", "navbar-nav"],
     "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
+    "show_version_warning_banner": True,
     # "show_nav_level": 2,
     # "navbar_start": ["navbar-logo"],
     # "navbar_end": ["theme-switcher", "navbar-icon-links"],

docs/user_guide/announcements.rst

@@ -38,3 +38,28 @@ For example, the following configuration tells the theme to load the ``custom-te
       ...
       "announcement": "https://github.com/pydata/pydata-sphinx-theme/raw/main/docs/_templates/custom-template.html",
    }
+
+Version warning banners
+-----------------------
+
+In addition to the general-purpose announcement banner, the theme includes a built-in banner to warn users when they are viewing versions of your docs other than the latest stable version. To use this feature, add the following to your ``conf.py``:
+
+.. code-block:: python
+
+    html_theme_options = {
+        ...
+        "show_version_warning_banner": True,
+    }
+
+.. warning::
+
+    This functionality relies on the :ref:`version switcher <version-dropdowns>` to determine the version number of the latest stable release.
+    *It will only work* if your version switcher ``.json`` has an entry with the version ``"stable"`` and a name that begins with a version string, for example:
+
+    .. code-block:: json
+
+        {
+            "name": "9.9.9 (current)",
+            "version": "stable",
+            "url": "https://anything"
+        }

docs/user_guide/version-dropdown.rst

@@ -1,3 +1,5 @@
+.. _version-dropdowns:
+
 Version switcher dropdowns
 ==========================
 

package.json

@@ -21,6 +21,7 @@
   "dependencies": {
     "@fortawesome/fontawesome-free": "6.1.2",
     "@popperjs/core": "^2.11.6",
-    "bootstrap": "^5.2.2"
+    "bootstrap": "^5.2.2",
+    "compare-versions": "^5.0.3"
   }
 }

src/pydata_sphinx_theme/__init__.py

@@ -273,6 +273,7 @@ def _remove_empty_templates(tname):
         js = f"""
         DOCUMENTATION_OPTIONS.theme_switcher_json_url = '{json_url}';
         DOCUMENTATION_OPTIONS.theme_switcher_version_match = '{version_match}';
+        DOCUMENTATION_OPTIONS.show_version_warning_banner = {str(context["theme_show_version_warning_banner"]).lower()};
         """
         app.add_js_file(None, body=js)
 

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -1,5 +1,6 @@
 // Define the custom behavior of the page
 import { documentReady } from "./mixin";
+import { compare } from "compare-versions";
 
 import "../styles/pydata-sphinx-theme.scss";
 
@@ -395,6 +396,75 @@ function initRTDObserver() {
   observer.observe(document.body, config);
 }
 
+/*******************************************************************************
+ * Warning banner when viewing non-stable version of the docs.
+ */
+function showVersionWarningBanner() {
+  // adapted 2023-05 from https://mne.tools/versionwarning.js, which was
+  // originally adapted 2020-05 from https://scikit-learn.org/versionwarning.js
+  const version = DOCUMENTATION_OPTIONS.VERSION;
+  // figure out what latest stable version is
+  var stableRelease = Infinity;
+  const menu = document.querySelector(".version-switcher__menu");
+  // fail early if not using the version selector
+  if (menu == null) {
+    return;
+  }
+  // from the menu, get the version number of the stable release
+  const releases = Array.from(menu.children);
+  const stableReleaseFromMenu = releases.filter(
+    (ver) => ver.getAttribute("data-version") == "stable"
+  )[0];
+  // hack to make sure the menu has been populated before we parse it
+  if (typeof stableReleaseFromMenu == "undefined") {
+    setTimeout(showVersionWarningBanner, 250);
+    return;
+  }
+  // isolate version string (the .split is in case the version
+  // string is something like "1.3 (stable)")
+  stableRelease = stableReleaseFromMenu
+    .getAttribute("data-version-name")
+    .split(" ")[0];
+  // now construct the warning banner
+  if (version !== "stable") {
+    var outer = document.createElement("div");
+    const middle = document.createElement("div");
+    const inner = document.createElement("div");
+    const bold = document.createElement("strong");
+
+    // Someday maybe we can add a button that pulls its target URL from
+    // the relevant "stable" entry of the version switcher menu:
+    // const button = document.createElement("a");
+    // button.href = `https://whatever/stable/${filePath}`;
+    // button.innerText = "Switch to latest stable version";
+    // button.classList = "sd-btn sd-btn-danger sd-shadow-sm sd-text-wrap font-weight-bold ms-3 my-3 align-baseline";
+
+    // these classes exist since pydata-sphinx-theme v0.10.0
+    outer.classList = "bd-header-version-warning container-fluid";
+    middle.classList = "bd-header-announcement__content";
+    inner.classList = "sidebar-message";
+    outer.appendChild(middle);
+    middle.appendChild(inner);
+    // for less-than comparison: "dev" → NaN → false (which is what we want)
+    inner.innerText = "This is documentation for ";
+    if (version.includes("dev") || compare(version, stableRelease, ">")) {
+      inner.innerText += "the ";
+      bold.innerText = "unstable development version";
+    } else {
+      inner.innerText += "an ";
+      bold.innerText = `old version (${version})`;
+    }
+    inner.appendChild(bold);
+    inner.appendChild(
+      document.createTextNode(
+        `. Use the version switcher dropdown to select the stable version.`
+      )
+    );
+    // inner.appendChild(button);
+    document.body.prepend(outer);
+  }
+}
+
 /*******************************************************************************
  * Call functions after document loading.
  */
@@ -404,3 +474,6 @@ documentReady(scrollToActive);
 documentReady(addTOCInteractivity);
 documentReady(setupSearchButtons);
 documentReady(initRTDObserver);
+if (DOCUMENTATION_OPTIONS.show_version_warning_banner) {
+  documentReady(showVersionWarningBanner);
+}

src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss

@@ -1,4 +1,5 @@
-.bd-header-announcement {
+.bd-header-announcement,
+.bd-header-version-warning {
   min-height: 3rem;
   width: 100%;
   display: flex;
@@ -25,7 +26,6 @@
     height: 100%;
     left: 0;
     top: 0;
-    background-color: var(--pst-color-info);
     opacity: 0.2;
     content: "";
     z-index: -1; // So it doesn't hover over the content
@@ -35,3 +35,15 @@
     display: none;
   }
 }
+
+.bd-header-announcement {
+  &:after {
+    background-color: var(--pst-color-info);
+  }
+}
+
+.bd-header-version-warning {
+  &:after {
+    background-color: var(--pst-color-danger);
+  }
+}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -50,6 +50,7 @@ footer_start = copyright.html, sphinx-version.html
 footer_end = theme-version.html
 secondary_sidebar_items = page-toc.html, edit-this-page.html, sourcelink.html
 announcement =
+show_version_warning_banner = False
 
 # DEPRECATE after 0.14
 footer_items =