Add version warning banner functionality

Adds a a warning banner to be shown on non-stable versions of the docs.
Inspired by pydata/pydata-sphinx-theme#780

src/napari_sphinx_theme/assets/styles/_base.scss

@@ -135,3 +135,25 @@ dl.field-list {
   display: grid;
   grid-template-columns: fit-content(30%) minmax(0, 1fr);
 }
+
+@mixin background-from-color-variable($color-variable, $opacity: 0.1) {
+  // This is a hack to create a light background with controlled opacity
+  // using our css color variables
+  // ref: https://stackoverflow.com/a/56951626/6734243
+
+  &:before {
+    content: "";
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    left: 0;
+    top: 0;
+    background-color: var(#{$color-variable});
+    opacity: $opacity;
+
+    // So that hovering over the text within background is still possible.
+    // Otherwise the background overlays the text and you cannot click or select easily.
+    // ref: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events
+    pointer-events: none;
+  }
+}

src/napari_sphinx_theme/assets/styles/_header-version-warning.scss

@@ -0,0 +1,35 @@
+/**
+ * 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/napari_sphinx_theme/assets/styles/index.scss

@@ -26,6 +26,7 @@ $grid-breakpoints: (
 @import "./markdown";
 @import "./versionmodified";
 @import "./announcement";
+@import "./header-version-warning";
 
 // Custom css, TODO: to be refactored in different partials
 // GitHub blockquote style

src/napari_sphinx_theme/theme/napari_sphinx_theme/_templates/version-switcher.html

@@ -62,17 +62,44 @@
             node.dataset["versionName"] = entry.name;
             node.dataset["version"] = entry.version;
 
+            // The version of the current documentation page
+            let currentVersion = "{{ theme_switcher.get('version_match') }}";
+
+            // Grab entry for the current version so we use it later
+            let currentVersionEntry = data.filter(entry => entry.version == currentVersion)[0];
+
             $("#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') }}") {
+            if (entry.version == currentVersion) {
                 node.classList.add("active");
                 let btn = document.getElementById("version_switcher_button");
                 btn.innerText = btn.dataset["activeVersionName"] = entry.name;
                 btn.dataset["activeVersion"] = entry.version;
             }
+
+            // If this entry is the one we wish to direct to
+            // And this entry is not currently active
+            // then add a banner to direct people there
+            if ((entry.preferred == "true") && (entry.version != currentVersion)) {
+                if (currentVersionEntry.description) {
+                    var currentVersionDescription = currentVersionEntry.description;
+                } else {
+                    var currentVersionDescription = "a previous release";
+                };
+                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>This page is for <strong>${currentVersionDescription}</strong>.</span>
+                        <a href="${entry.url}${currentFilePath}"><button class="btn">Switch to: ${entry.name}</button></a>
+                    </div>
+                </div>
+                `);
+                console.log("[PST]: Inserted version warning banner...");
+            }
         });
     });
 })();

src/napari_sphinx_theme/theme/napari_sphinx_theme/layout.html

@@ -46,6 +46,8 @@
     {# Added to support a banner with an alert #}
     {%- include "announcement.html" -%}
 
+    {% include "version-warning.html" %}
+
     <div class="napari-page">
         {% block docs_sidebar %}
           {% if sidebars %}

src/napari_sphinx_theme/theme/napari_sphinx_theme/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 -%}