From df5d59ada04eb6cd9f40ff1a4fc9aa37b3e372cb Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 29 Jun 2023 02:03:06 -0400 Subject: [PATCH] DOC: Restore banner indicating docs are unreleased 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. --- doc/_static/mpl.css | 23 +++++++++++++++++++++++ doc/_templates/sections/announcement.html | 13 +++++++++++++ doc/conf.py | 6 +++++- 3 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 doc/_templates/sections/announcement.html diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index 14a2b4732295..e9d7d65f3e01 100644 --- 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 new file mode 100644 index 000000000000..b134acef9af5 --- /dev/null +++ b/doc/_templates/sections/announcement.html @@ -0,0 +1,13 @@ +{%- if theme_announcement == "unreleased" -%} +{% set header_classes = ["bd-header-announcement", "container-fluid"] %} +
+
+ You are reading documentation for the unreleased version of Matplotlib. + + Try searching for the released version of this page instead? + +
+
+{%- else -%} + {%- extends "!sections/announcement.html" -%} +{%- endif %} diff --git a/doc/conf.py b/doc/conf.py index ce34993c3e8d..5375dba8f0ab 100644 --- 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: