docs: Fix for missing jQuery (#2416)

As mentioned in discord, the current build of the docs loses jQuery
functionality. This is due to sphinx being upgraded to version 6 in
which they removed jQuery and created a stand-alone package for it.

Additionally, in the process of doing that, I noticed the previously
mentioned fix (in the comments) for the `melos doc-setup` about removing
the single quotes to keep it clean didn't make into the final code. I
have updated that as it was previously confirmed to work on all
platforms in: https://github.com/flame-engine/flame/pull/2401

I noticed that the copyright that was in the `conf.py` was locked at
2021 and so I made it go to 2023 as well. This can be removed if not
desired, but thought maybe this had just been overlooked.

Finally, there was an error regarding a duplicate instantiation of a
constant. This had to do with the fact the basic theme provided with
sphinx, the next version after which the docs were based, had a bug fix
implemented:
https://www.sphinx-doc.org/en/master/changes.html#release-5-1-0-released-jul-24-2022.
In their fix, it also broke the way the flames theme works. On a side
note, the docs are using a very outdated version of the basic theme and
should likely be overhauled, but that is outside the scope of this pr.
None the less, after I finally figured out how the basic theme is
inherited and where that lived on my machine, I was able to resolve the
discrepancies and eliminate the conflicting names between the two
themes.

In short, all errors have been resolved and I have confirmed that
mobile, web, search, highlighting, menus, etc. all work - at least on my
machine.

doc/_sphinx/conf.py

@@ -36,6 +36,7 @@ extensions = [
     'extensions.flutter_app',
     'extensions.package',
     'extensions.yarn_lexer',
+    'sphinxcontrib.jquery',
 ]
 
 # Configuration options for MyST:

doc/_sphinx/requirements.txt

@@ -3,6 +3,7 @@ myst-parser==1.0.0
 Pygments==2.14.0
 Sphinx==6.1.3
 sphinxcontrib-mermaid==0.8.1
+sphinxcontrib-jquery==4.0
 sphinx-autobuild==2021.3.14
 Jinja2==3.1.2
 psutil==5.9.4

doc/_sphinx/theme/doctools.js

@@ -21,11 +21,18 @@ const _ready = (callback) => {
   }
 };
 
+const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
+  "TEXTAREA",
+  "INPUT",
+  "SELECT",
+  "BUTTON",
+]);
+
 /**
  * highlight a given string on a node by wrapping it in
  * span elements with the given class name.
  */
-const _highlight = (node, addItems, text, className, index) => {
+const _highlightFlame = (node, addItems, text, className, index) => {
   if (node.nodeType === Node.TEXT_NODE) {
     const val = node.nodeValue;
     const parent = node.parentNode;
@@ -72,12 +79,12 @@ const _highlight = (node, addItems, text, className, index) => {
       }
     }
   } else if (node.matches && !node.matches("button, select, textarea")) {
-    node.childNodes.forEach((el) => _highlight(el, addItems, text, className, index));
+    node.childNodes.forEach((el) => _highlightFlame(el, addItems, text, className, index));
   }
 };
-const _highlightText = (thisNode, text, className, index) => {
+const _highlightTextFlame = (thisNode, text, className, index) => {
   let addItems = [];
-  _highlight(thisNode, addItems, text, className, index);
+  _highlightFlame(thisNode, addItems, text, className, index);
   addItems.forEach((obj) =>
     obj.parent.insertAdjacentElement("beforebegin", obj.target)
   );
@@ -86,11 +93,11 @@ const _highlightText = (thisNode, text, className, index) => {
 /**
  * Small JavaScript module for the documentation.
  */
-const Documentation = {
+const DocumentationFlame = {
   init: () => {
-    Documentation.highlightSearchWords();
+    DocumentationFlame.highlightSearchWords();
-    Documentation.initDomainIndexTable();
+    DocumentationFlame.initDomainIndexTable();
-    Documentation.initOnKeyListeners();
+    DocumentationFlame.initOnKeyListeners();
   },
 
   /**
@@ -101,9 +108,9 @@ const Documentation = {
   LOCALE: "unknown",
 
   // gettext and ngettext don't access this so that the functions
-  // can safely bound to a different name (_ = Documentation.gettext)
+  // can safely bound to a different name (_ = DocumentationFlame.gettext)
   gettext: (string) => {
-    const translated = Documentation.TRANSLATIONS[string];
+    const translated = DocumentationFlame.TRANSLATIONS[string];
     switch (typeof translated) {
       case "undefined":
         return string; // no translation
@@ -115,19 +122,19 @@ const Documentation = {
   },
 
   ngettext: (singular, plural, n) => {
-    const translated = Documentation.TRANSLATIONS[singular];
+    const translated = DocumentationFlame.TRANSLATIONS[singular];
     if (typeof translated !== "undefined")
-      return translated[Documentation.PLURAL_EXPR(n)];
+      return translated[DocumentationFlame.PLURAL_EXPR(n)];
     return n === 1 ? singular : plural;
   },
 
   addTranslations: (catalog) => {
-    Object.assign(Documentation.TRANSLATIONS, catalog.messages);
+    Object.assign(DocumentationFlame.TRANSLATIONS, catalog.messages);
-    Documentation.PLURAL_EXPR = new Function(
+    DocumentationFlame.PLURAL_EXPR = new Function(
       "n",
       `return (${catalog.plural_expr})`
     );
-    Documentation.LOCALE = catalog.locale;
+    DocumentationFlame.LOCALE = catalog.locale;
   },
 
   /**
@@ -145,16 +152,16 @@ const Documentation = {
     const hbox = $("#highlight-content");
     window.setTimeout(() => {
       terms.forEach((term, index) => {
-        _highlightText(body, term, "highlighted", index);
+        _highlightTextFlame(body, term, "highlighted", index);
         hbox.append($('<span>' + term + '</span>').click(function(){
           $(this).toggleClass("off");
-          Documentation.toggleSearchWord(index);
+          DocumentationFlame.toggleSearchWord(index);
         }));
       });
     }, 10);
 
     $("div.highlight-box").show();
-    $("div.highlight-box button.close").click(Documentation.hideSearchWords);
+    $("div.highlight-box button.close").click(DocumentationFlame.hideSearchWords);
     const searchBox = document.getElementById("searchbox");
     if (searchBox === null) return;
     searchBox.appendChild(
@@ -162,8 +169,8 @@ const Documentation = {
         .createRange()
         .createContextualFragment(
           '<p class="highlight-link">' +
-            '<a href="javascript:Documentation.hideSearchWords()">' +
+            '<a href="javascript:DocumentationFlame.hideSearchWords()">' +
-            Documentation.gettext("Hide Search Matches") +
+            DocumentationFlame.gettext("Hide Search Matches") +
             "</a></p>"
         )
     );
@@ -228,14 +235,8 @@ const Documentation = {
     )
       return;
 
-    const blacklistedElements = new Set([
-      "TEXTAREA",
-      "INPUT",
-      "SELECT",
-      "BUTTON",
-    ]);
     document.addEventListener("keydown", (event) => {
-      if (blacklistedElements.has(document.activeElement.tagName)) return; // bail for input elements
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; // bail for input elements
       if (event.altKey || event.ctrlKey || event.metaKey) return; // bail with special keys
 
       if (!event.shiftKey) {
@@ -260,7 +261,7 @@ const Documentation = {
             break;
           case "Escape":
             if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
-            Documentation.hideSearchWords();
+            DocumentationFlame.hideSearchWords();
             event.preventDefault();
         }
       }
@@ -269,7 +270,7 @@ const Documentation = {
       switch (event.key) {
         case "/":
           if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
-          Documentation.focusSearchBar();
+          DocumentationFlame.focusSearchBar();
           event.preventDefault();
       }
     });
@@ -277,6 +278,6 @@ const Documentation = {
 };
 
 // quick alias for translations
-const _ = Documentation.gettext;
+const _ = DocumentationFlame.gettext;
 
-_ready(Documentation.init);
+_ready(DocumentationFlame.init);

melos.yaml

@@ -48,15 +48,15 @@ scripts:
 
   doc-setup:
     run: >
-      echo 'Checking python version:' &&
+      echo Checking python version: &&
       python --version &&
       (python -c "import sys; sys.exit(0 if sys.version_info >= (3,8) else 2)" ||
-      (echo  'Error: Python 3.8+ is required' && exit 1)) &&
+      (echo  Error: Python 3.8+ is required && exit 1)) &&
-      echo 'Installing required python modules:' &&
+      echo Installing required python modules: &&
       python -m pip install -r "$MELOS_ROOT_PATH/doc/_sphinx/requirements.txt" &&
-      echo 'Installing dartdoc_json:' &&
+      echo Installing dartdoc_json: &&
       dart pub global activate dartdoc_json &&
-      echo 'Done.'
+      echo Done.
     description: Prepares the environment for documentation development.
 
   doc-build: