docs: Add warning to version-specific docunmentation pages (#2248)

See details on issue #2214
Basically, we want to make users more aware they are looking at old version of the docs.

doc/_sphinx/scripts/versions.js

@@ -33,9 +33,22 @@ function convertVersionsToHtmlLinks(versionsList, currentVersion) {
   return out;
 }
 
+function maybeAddWarning(versions, currentVersion) {
+  const specialVersions = ['main', 'local'];
+  const latestVersion = versions.filter(e => !specialVersions.includes(e))[0];
+  const nonWarningVersions = [...specialVersions, latestVersion];
+  const showWarning = !nonWarningVersions.includes(currentVersion);
+  if (showWarning) {
+    $('#version-warning')
+      .find('.version').text(currentVersion).end()
+      .removeClass('hidden');
+  }
+}
+
 function buildVersionsMenu(data) {
+  const versions = data.split('\n');
   const currentVersion = getCurrentDocVersion();
-  const versionButtons = convertVersionsToHtmlLinks(data.split('\n'), currentVersion);
+  const versionButtons = convertVersionsToHtmlLinks(versions, currentVersion);
   $('div.versions-placeholder').append(`
     <div id="versions-menu" tabindex="-1">
       <div class="btn">
@@ -54,6 +67,8 @@ function buildVersionsMenu(data) {
     // A timeout ensures that `click` can propagate to child <A/> elements.
     setTimeout(() => $(this).removeClass("active"), 200);
   });
+
+  maybeAddWarning(versions, currentVersion);
 }
 
 // Start loading the versions list as soon as possible, don't wait for DOM

doc/_sphinx/theme/flames.css

@@ -473,6 +473,24 @@ div.document-wrapper {
   margin-top: 25px;
 }
 
+div.warning {
+  background: #9b6814;
+  color: white;
+  border-radius: 2pt;
+  box-shadow: 2px 2px 3px #ffc43c;
+  padding: 16px;
+  margin-bottom: 16px;
+}
+
+div.warning .version {
+  font-style: italic;
+  text-decoration: dashed underline;
+}
+
+.hidden {
+  display: none;
+}
+
 div.document {
   background-color: #282828;
   color: #b0b0b0;

doc/_sphinx/theme/layout.html

@@ -124,6 +124,12 @@
 
 <div class="main-area">
   <div class="document-wrapper">
+    <div class="warning hidden" id="version-warning">
+      <p><strong>Warning:</strong> you are currently viewing the docs for an older
+      version <span class="version"></span> of Flame.</p>
+      <p>Please <a href="/">click here</a> to go see the documentation for the latest
+      released version.</p>
+    </div>
     <div class="document" role="main">
       {% block body %} {% endblock %}
     </div>