diff --git a/doc/_sphinx/conf.py b/doc/_sphinx/conf.py index a867ca90d..b0ea06c92 100644 --- a/doc/_sphinx/conf.py +++ b/doc/_sphinx/conf.py @@ -36,6 +36,7 @@ extensions = [ 'extensions.flutter_app', 'extensions.package', 'extensions.yarn_lexer', + 'sphinxcontrib.jquery', ] # Configuration options for MyST: diff --git a/doc/_sphinx/requirements.txt b/doc/_sphinx/requirements.txt index d04aab768..6b83b728c 100644 --- a/doc/_sphinx/requirements.txt +++ b/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 diff --git a/doc/_sphinx/theme/doctools.js b/doc/_sphinx/theme/doctools.js index 6e16f023a..0d3ab90f8 100644 --- a/doc/_sphinx/theme/doctools.js +++ b/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(); - Documentation.initDomainIndexTable(); - Documentation.initOnKeyListeners(); + DocumentationFlame.highlightSearchWords(); + DocumentationFlame.initDomainIndexTable(); + 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); - Documentation.PLURAL_EXPR = new Function( + Object.assign(DocumentationFlame.TRANSLATIONS, catalog.messages); + 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($('' + term + '').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( '" ) ); @@ -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); diff --git a/melos.yaml b/melos.yaml index 96c8e8d14..9fb483a67 100644 --- a/melos.yaml +++ b/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 'Installing required python modules:' && + (echo Error: Python 3.8+ is required && exit 1)) && + 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: