From 64bc0942fb8682a394ab9d5d3b4605cea8bf1afa Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 29 Nov 2021 16:29:45 -0500 Subject: [PATCH 1/4] add warning banner js --- docs/sphinx/source/_static/version-alert.js | 34 +++++++++++++++++++++ docs/sphinx/source/conf.py | 2 ++ 2 files changed, 36 insertions(+) create mode 100644 docs/sphinx/source/_static/version-alert.js diff --git a/docs/sphinx/source/_static/version-alert.js b/docs/sphinx/source/_static/version-alert.js new file mode 100644 index 0000000000..4c053254ad --- /dev/null +++ b/docs/sphinx/source/_static/version-alert.js @@ -0,0 +1,34 @@ +"use strict"; + +// Source: +// https://github.com/anymail/django-anymail/blob/4c443f5515d1d5269a95cb54cf75057c56a3b150/docs/_static/version-alert.js +// via: +// https://github.com/qucontrol/krotov/blob/969fc980346e6411903de854118c48c51208a810/docs/_static/version-alert.js +// following instructions here: +// https://michaelgoerz.net/notes/showing-a-warning-for-the-latest-documentation-on-readthedocs.html + +function warnOnLatestVersion() { + + // The warning text and link is really specific to RTD hosting, + // so we can just check their global to determine version: + if (!window.READTHEDOCS_DATA || window.READTHEDOCS_DATA.version !== "latest") { + return; // not latest, or not on RTD + } + + var warning = document.createElement('div'); + warning.setAttribute('class', 'admonition danger'); + warning.innerHTML = "

Note

" + + "

" + + "This document is for an unreleased development version. " + + "Documentation is available for the current stable release, " + + "or for older versions through the “v:” menu at bottom left." + + "

"; + warning.querySelector('a').href = window.location.pathname.replace('/latest', '/stable'); + + var parent = document.querySelector('div.body') + || document.querySelector('div.document') + || document.body; + parent.insertBefore(warning, parent.firstChild); +} + +document.addEventListener('DOMContentLoaded', warnOnLatestVersion); diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index b99dc48302..b6ba3e54b7 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -223,6 +223,8 @@ def setup(app): # Override footnote callout CSS to be normal text instead of superscript # In-line links to references as numbers in brackets. app.add_css_file("reference_format.css") + # Add a warning banner at the top of the page if viewing the "latest" docs + app.add_javascript("version-alert.js") # -- Options for LaTeX output --------------------------------------------- From f215e79ff757c4a8bf091bdbea2244b392fc8765 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 8 Dec 2021 07:55:00 -0500 Subject: [PATCH 2/4] modify for pydata sphinx theme --- docs/sphinx/source/_static/version-alert.js | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/_static/version-alert.js b/docs/sphinx/source/_static/version-alert.js index 4c053254ad..4a9244934d 100644 --- a/docs/sphinx/source/_static/version-alert.js +++ b/docs/sphinx/source/_static/version-alert.js @@ -25,9 +25,8 @@ function warnOnLatestVersion() { "

"; warning.querySelector('a').href = window.location.pathname.replace('/latest', '/stable'); - var parent = document.querySelector('div.body') - || document.querySelector('div.document') - || document.body; + // modified from original to work better w/ pydata sphinx theme + var parent = document.querySelector('main') || document.body; parent.insertBefore(warning, parent.firstChild); } From d6f006ae043877124f65019b71004e9d895a628a Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 8 Dec 2021 07:56:04 -0500 Subject: [PATCH 3/4] another tweak --- docs/sphinx/source/_static/version-alert.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/_static/version-alert.js b/docs/sphinx/source/_static/version-alert.js index 4a9244934d..0540cf8754 100644 --- a/docs/sphinx/source/_static/version-alert.js +++ b/docs/sphinx/source/_static/version-alert.js @@ -21,7 +21,7 @@ function warnOnLatestVersion() { "

" + "This document is for an unreleased development version. " + "Documentation is available for the current stable release, " + - "or for older versions through the “v:” menu at bottom left." + + "or for older versions through the “v:” menu at bottom right." + "

"; warning.querySelector('a').href = window.location.pathname.replace('/latest', '/stable'); From 01bec0f2fcecf2d20ac25e0b5d4414512d82d848 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Wed, 8 Dec 2021 10:46:54 -0500 Subject: [PATCH 4/4] reproduce original license text --- docs/sphinx/source/_static/version-alert.js | 30 +++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/_static/version-alert.js b/docs/sphinx/source/_static/version-alert.js index 0540cf8754..e8179a6c2f 100644 --- a/docs/sphinx/source/_static/version-alert.js +++ b/docs/sphinx/source/_static/version-alert.js @@ -1,9 +1,35 @@ "use strict"; +// Copyright (c) Anymail Contributors. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without modification, +// are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in the +// documentation and/or other materials provided with the distribution. +// +// 3. Neither the name of the copyright holder nor the names of its contributors +// may be used to endorse or promote products derived from this software +// without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR +// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +// ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + // Source: // https://github.com/anymail/django-anymail/blob/4c443f5515d1d5269a95cb54cf75057c56a3b150/docs/_static/version-alert.js -// via: -// https://github.com/qucontrol/krotov/blob/969fc980346e6411903de854118c48c51208a810/docs/_static/version-alert.js // following instructions here: // https://michaelgoerz.net/notes/showing-a-warning-for-the-latest-documentation-on-readthedocs.html