DOC: Restore banner indicating docs are unreleased

QuLogic · QuLogic · commit df5d59ada04e · 2023-07-05T20:04:03.000-04:00
This was dropped when switching to the pydata-sphinx-theme. They have a
method of adding an announcement, but because it's a pure text
substitution, we can't have it automatically search like our old banner.

While the theme also supports loading from an http resource, that would
mean writing some JavaScript instead of automatically creating this div
at build time.

So override the theme component, and create the search link at build
time.
diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css
@@ -9,6 +9,29 @@
     margin: 0;
 }
 
+/* Make announcement an error colour for unreleased documentation, and sticky. */
+#unreleased-message.bd-header-announcement {
+    border-bottom: solid var(--pst-color-danger-highlight);
+    color: var(--pst-color-danger-text);
+    font-weight: var(--pst-admonition-font-weight-heading);
+    position: sticky;
+    top: 0;
+    z-index: 1050;
+}
+
+#unreleased-message.bd-header-announcement:after {
+    background-color: var(--pst-color-danger);
+    opacity: 1;
+}
+
+#unreleased-message.bd-header-announcement a {
+    color: var(--pst-color-danger-text);
+}
+
+#unreleased-message.bd-header-announcement + .bd-navbar {
+    top: 3rem;  /* Minimum height of announcement header. */
+}
+
 /* multi column TOC */
 .contents ul {
     list-style-type: none;
diff --git a/doc/_templates/sections/announcement.html b/doc/_templates/sections/announcement.html
@@ -0,0 +1,13 @@
+{%- if theme_announcement == "unreleased" -%}
+{% set header_classes = ["bd-header-announcement", "container-fluid"] %}
+  <div class="{{ header_classes | join(' ') }}" id="unreleased-message">
+    <div class="bd-header-announcement__content">
+      You are reading documentation for the unreleased version of Matplotlib.
+      <a href="https://matplotlib.org/search.html?q={{ title | striptags | urlencode }}&amp;check_keywords=yes&amp;area=default">
+        Try searching for the released version of this page instead?
+      </a>
+    </div>
+  </div>
+{%- else -%}
+  {%- extends "!sections/announcement.html" -%}
+{%- endif %}
diff --git a/doc/conf.py b/doc/conf.py
@@ -462,7 +462,11 @@ def js_tag_with_cache_busting(js):
     },
     "navbar_end": ["theme-switcher", "version-switcher", "mpl_icon_links"],
     "secondary_sidebar_items": "page-toc.html",
-     "footer_start": ["copyright", "sphinx-version", "doc_version"],
+    "footer_start": ["copyright", "sphinx-version", "doc_version"],
+    # We override the announcement template from pydata-sphinx-theme, where
+    # this special value indicates the use of the unreleased banner. If we need
+    # an actual announcement, then just place the text here as usual.
+    "announcement": "unreleased" if not is_release_build else "",
 }
 include_analytics = is_release_build
 if include_analytics:
