Docs: prep for upcoming RTD build changes

Read the Docs is changing their build process. Some docs/conf.py
manipulation they used to do automatically now must be manually
included.

https://about.readthedocs.com/blog/2024/07/addons-by-default/

Related changes:

* Drop our version-alert.js. RTD's new "addons" includes
  equivalent warning on unreleased versions.

* Integrate Google Analytics via sphinxcontrib-googleanalytics
  when GOOGLE_ANALYTICS_ID is set in docs build environment.

docs/_static/version-alert.js

@@ -1,38 +0,0 @@
-"use strict";
-
-// Similar to https://github.com/readthedocs/readthedocs.org/blob/5.2.3/readthedocs/core/static-src/core/js/doc-embed/version-compare.js
-// but adds admonition for the "latest" version -- which is (unreleased) main branch.
-
-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 left." +
-    "</p>";
-  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);
-}
-
-if (document.readyState === "loading") {
-  document.addEventListener("DOMContentLoaded", warnOnLatestVersion);
-} else {
-  warnOnLatestVersion();
-}

docs/conf.py

@@ -15,7 +15,7 @@ from pathlib import Path
 
 from anymail import VERSION as PACKAGE_VERSION
 
-ON_READTHEDOCS = os.environ.get("READTHEDOCS", None) == "True"
+ON_READTHEDOCS = os.environ.get("READTHEDOCS") == "True"
 DOCS_PATH = Path(__file__).parent
 PROJECT_ROOT_PATH = DOCS_PATH.parent
 
@@ -31,7 +31,12 @@ needs_sphinx = "1.0"
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.intersphinx", "sphinx.ext.extlinks", "sphinx_rtd_theme"]
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.extlinks",
+    "sphinx_rtd_theme",
+    "sphinxcontrib.googleanalytics",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -96,6 +101,12 @@ pygments_style = "sphinx"
 
 # -- Options for HTML output ---------------------------------------------------
 
+# Set canonical URL from the Read the Docs Domain.
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+# Let templates know whether the build is running on Read the Docs.
+html_context = {"READTHEDOCS": ON_READTHEDOCS}
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "sphinx_rtd_theme"
@@ -271,14 +282,23 @@ intersphinx_mapping = {
     "urllib3": ("https://urllib3.readthedocs.io/en/stable/", None),
 }
 
+# -- Options for Google Analytics -------------------------------------------
 
+googleanalytics_id = os.environ.get("GOOGLE_ANALYTICS_ID", "")
+googleanalytics_enabled = bool(googleanalytics_id)
+
+if not googleanalytics_enabled:
+    # Work around https://github.com/sphinx-contrib/googleanalytics/issues/14.
+    googleanalytics_id = "IGNORED"
+
+
+# -- App setup --------------------------------------------------------------
 def setup(app):
     app.add_css_file("anymail-theme.css")
     # Inline <script> for anymail-config.js to avoid non-async JS load:
     # app.add_js_file("anymail-config.js")
     anymail_config_js = (DOCS_PATH / "_static/anymail-config.js").read_text()
     app.add_js_file(None, body=anymail_config_js)
-    app.add_js_file("version-alert.js", **{"async": "async"})
     app.add_js_file("table-formatting.js", **{"async": "async"})
     app.add_js_file("https://unpkg.com/rate-the-docs", **{"async": "async"})
 

docs/requirements.txt

@@ -4,3 +4,4 @@ Pygments~=2.16.1
 readme-renderer~=41.0
 sphinx~=7.2
 sphinx-rtd-theme~=2.0.0
+sphinxcontrib-googleanalytics~=0.4

tox.ini

@@ -106,6 +106,7 @@ commands =
 basepython = python3.11
 passenv =
     CONTINUOUS_INTEGRATION
+    GOOGLE_ANALYTICS_ID
 	# (but not any of the live test API keys)
 setenv =
     DOCS_BUILD_DIR={envdir}/_html