Prevent the compatibility notice from being the meta description

Adding the compatibility notice via JavaScript prevents the `meta description` Sphinx extension from taking the notice as part of the description. This also changes the redirect URL to point to the page the user is currently reading instead of always pointing to the homepage.
Sightwalker · Sep 22, 2020 · bdece44 · bdece44
1 parent 5a96e5f
commit bdece44
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 21 deletions.
diff --git a/_static/js/custom.js b/_static/js/custom.js
@@ -1,3 +1,9 @@
+
+// Set this to `true` when the `latest` branch is significantly incompatible with the
+// current `stable` branch, which can lead to confusion for users that land on
+// `latest` instead of `stable`.
+const inDev = true;
+
 // Handle page scroll and adjust sidebar accordingly.
 
 // Each page has two scrolls: the main scroll, which is moving the content of the page;
@@ -202,6 +208,26 @@ $(document).ready(() => {
     registerOnScrollEvent(mediaQuery);
   });
 
+  if (inDev) {
+    // Add a compatibility notice using JavaScript so it doesn't end up in the
+    // automatically generated `meta description` tag.
+    const url = window.location.href.replace('/latest/', '/stable/');
+    document.querySelector('div[itemprop="articleBody"]').insertAdjacentHTML('afterbegin', `
+      <div class="admonition attention">
+        <p class="first admonition-title">Attention</p>
+        <p>
+          You are reading the <code class="docutils literal notranslate"><span class="pre">latest</span></code>
+          (unstable) version of this documentation, which may document features not available
+          or compatible with Godot 3.2.x.
+        </p>
+        <p class="last">
+          See <a class="reference" href="${url}">this page</a>
+          for the stable version of this documentation.
+        </p>
+      </div>
+    `);
+  }
+
   // Load instant.page to prefetch pages upon hovering. This makes navigation feel
   // snappier. The script is dynamically appended as Read the Docs doesn't have
   // a way to add scripts with a "module" attribute.

diff --git a/conf.py b/conf.py
@@ -52,11 +52,6 @@
 # The full version, including alpha/beta/rc tags
 release = version
 
-# Set this True when the `latest` branch is significantly incompatible with the
-# current `stable` branch, which can lead to confusion for users that land on
-# `latest` instead of `stable`.
-in_dev = True
-
 # Parse Sphinx tags passed from RTD via environment
 env_tags = os.getenv("SPHINX_TAGS")
 if env_tags is not None:
@@ -235,22 +230,6 @@ def godot_get_image_filename_for_language(filename, env):
 
 sphinx.util.i18n.get_image_filename_for_language = godot_get_image_filename_for_language
 
-# Read the Docs adds a note at the top of the page when reading documentation
-# for an old stable version, but not when reading the latest unstable version.
-# We want to add a warning note as the `latest` documentation may not always
-# apply to the current `stable` version.
-if in_dev:
-    rst_prolog = """
-.. attention::
-    You are reading the ``latest`` (unstable) version of this documentation,
-    which may document features not available or compatible with Godot 3.2.x.
-
-    See `this page <https://docs.godotengine.org/{locale}/stable/>`__
-    for the stable version of this documentation.
-""".format(
-        locale=language,
-    )
-
 # Couldn't find a way to retrieve variables nor do advanced string
 # concat from reST, so had to hardcode this in the "epilog" added to
 # all pages. This is used in index.rst to display the Weblate badge.