Skip to content

Commit

Permalink
docs: Fix for missing jQuery (flame-engine#2416)
Browse files Browse the repository at this point in the history 
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: flame-engine#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.
  • Loading branch information
@munsterlander
munsterlander authored Mar 18, 2023
1 parent 277bd5d commit b5af714
Show file tree
Hide file tree
Showing 4 changed files with 39 additions and 36 deletions.
1 change: 1 addition & 0 deletions doc/_sphinx/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
'extensions.flutter_app',
'extensions.package',
'extensions.yarn_lexer',
'sphinxcontrib.jquery',
]

# Configuration options for MyST:
Expand Down
1 change: 1 addition & 0 deletions doc/_sphinx/requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
63 changes: 32 additions & 31 deletions doc/_sphinx/theme/doctools.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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)
);
Expand All @@ -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();
},

/**
Expand All @@ -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
Expand All @@ -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;
},

/**
Expand All @@ -145,25 +152,25 @@ 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(
document
.createRange()
.createContextualFragment(
'<p class="highlight-link">' +
'<a href="javascript:Documentation.hideSearchWords()">' +
Documentation.gettext("Hide Search Matches") +
'<a href="javascript:DocumentationFlame.hideSearchWords()">' +
DocumentationFlame.gettext("Hide Search Matches") +
"</a></p>"
)
);
Expand Down Expand Up @@ -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) {
Expand All @@ -260,7 +261,7 @@ const Documentation = {
break;
case "Escape":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.hideSearchWords();
DocumentationFlame.hideSearchWords();
event.preventDefault();
}
}
Expand All @@ -269,14 +270,14 @@ const Documentation = {
switch (event.key) {
case "/":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.focusSearchBar();
DocumentationFlame.focusSearchBar();
event.preventDefault();
}
});
},
};

// quick alias for translations
const _ = Documentation.gettext;
const _ = DocumentationFlame.gettext;

_ready(Documentation.init);
_ready(DocumentationFlame.init);
10 changes: 5 additions & 5 deletions melos.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit b5af714

Please sign in to comment.