Add version warning banner for "latest" sphinx docs (#1346)

* add warning banner js

* modify for pydata sphinx theme

* another tweak

* reproduce original license text

Author: kandersolar

docs/sphinx/source/_static/version-alert.js

@@ -0,0 +1,59 @@
+"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
+// 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 = "<p class='first admonition-title'>Note</p> " +
+    "<p class='last'> " +
+    "This document is for an <strong>unreleased development version</strong>. " +
+    "Documentation is available for the <a href='/en/stable/'>current stable release</a>, " +
+    "or for older versions through the &ldquo;v:&rdquo; menu at bottom right." +
+    "</p>";
+  warning.querySelector('a').href = window.location.pathname.replace('/latest', '/stable');
+
+  // modified from original to work better w/ pydata sphinx theme
+  var parent = document.querySelector('main') || document.body;
+  parent.insertBefore(warning, parent.firstChild);
+}
+
+document.addEventListener('DOMContentLoaded', warnOnLatestVersion);

docs/sphinx/source/conf.py

@@ -241,6 +241,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 ---------------------------------------------