From 1da407b9216683ff1b0386b1d4ee9561cd75d105 Mon Sep 17 00:00:00 2001
From: Yuri Sizov <yuris@humnom.net>
Date: Fri, 24 Feb 2023 19:14:55 +0100
Subject: [PATCH] Move the latest branch warning into templates

---
 _static/js/custom.js   | 31 +++++++++----------------------
 _templates/layout.html | 33 ++++++++++++++++++++++++++++++---
 conf.py                |  3 +++
 3 files changed, 42 insertions(+), 25 deletions(-)

diff --git a/_static/js/custom.js b/_static/js/custom.js
index 899bc76c0..03ae375db 100644
--- a/_static/js/custom.js
+++ b/_static/js/custom.js
@@ -1,9 +1,4 @@
 
-// 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;
@@ -296,7 +291,9 @@ $(document).ready(() => {
     }
   }
 
-  if (inDev) {
+  // See `godot_is_latest` in conf.py
+  const isLatest = document.querySelector('meta[name=doc_is_latest]').content.toLowerCase() === 'true';
+  if (isLatest) {
     // Add a compatibility notice using JavaScript so it doesn't end up in the
     // automatically generated `meta description` tag.
 
@@ -306,24 +303,14 @@ $(document).ready(() => {
     const homeUrl = baseUrl.split('/latest/')[0] + '/stable/';
     const searchUrl = homeUrl + 'search.html?q=';
 
-    // Insert the base notice with a placeholder to display as we're making a request.
-    document.querySelector('div[itemprop="articleBody"]').insertAdjacentHTML('afterbegin', `
-      <div class="admonition attention latest-notice">
-        <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.x.
-        </p>
-        <p class="last latest-notice-link">
-          Checking the <a class="reference" href="${homeUrl}">stable version</a>
-          of the documentation...
-        </p>
-      </div>
-    `);
-
     const noticeLink = document.querySelector('.latest-notice-link');
 
+    // Insert a placeholder to display as we're making a request.
+    noticeLink.innerHTML = `
+    Checking the <a class="reference" href="${homeUrl}">stable version</a>
+    of the documentation...
+    `;
+
     // Make a HEAD request to the possible stable URL to check if the page exists.
     fetch(fallbackUrl, { method: 'HEAD' })
       .then((res) => {
diff --git a/_templates/layout.html b/_templates/layout.html
index 9cafebd1d..0972947d1 100644
--- a/_templates/layout.html
+++ b/_templates/layout.html
@@ -1,7 +1,12 @@
 {% extends "!layout.html" -%}
 
+{% block htmltitle -%}
+<title>{{ godot_title_prefix }}{{ title|striptags|e }}{{ titlesuffix }}</title>
+{% endblock -%}
+
 {% block extrahead -%}
 <meta name="doc_version" content="{{ version }}">
+<meta name="doc_is_latest" content="{{ godot_is_latest }}">
 {% endblock -%}
 
 {% block linktags -%}
@@ -19,6 +24,28 @@
   {{ super() }}
 {% endblock -%}
 
-{% block htmltitle -%}
-<title>{{ godot_title_prefix }}{{ title|striptags|e }}{{ titlesuffix }}</title>
-{% endblock -%}
+{%- block document %}
+<div itemprop="articleBody">
+  {% if godot_is_latest %}
+  <div class="admonition attention latest-notice">
+    <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.x.
+    </p>
+    <p class="last latest-notice-link">
+      Checking the stable version of the documentation...
+    </p>
+  </div>
+  {% endif %}
+
+  {% block body %}{% endblock %}
+</div>
+{%- if self.comments()|trim %}
+  <div class="articleComments">
+    {%- block comments %}{% endblock %}
+  </div>
+{%- endif%}
+</div>
+{%- endblock %}
diff --git a/conf.py b/conf.py
index 9f0062deb..0a31c9171 100644
--- a/conf.py
+++ b/conf.py
@@ -175,6 +175,9 @@ html_context = {
     # Distinguish local development website from production website.
     # This prevents people from looking for changes on the production website after making local changes :)
     "godot_title_prefix": "" if on_rtd else "(DEV) ",
+    # Set this to `True` when in the `latest` branch to clearly indicate to the reader
+    # that they are not reading the `stable` documentation.
+    "godot_is_latest": True,
 }
 
 html_logo = "img/docs_logo.svg"