Reticulum/docs/manual/_static/doctools.js

157 lines
4.4 KiB
JavaScript
Raw Normal View History

2021-05-16 21:40:49 +00:00
/*
* doctools.js
* ~~~~~~~~~~~
*
2022-09-29 22:02:15 +00:00
* Base JavaScript utilities for all Sphinx HTML documentation.
2021-05-16 21:40:49 +00:00
*
2024-05-05 17:56:33 +00:00
* :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
2021-05-16 21:40:49 +00:00
* :license: BSD, see LICENSE for details.
*
*/
2022-09-29 22:02:15 +00:00
"use strict";
const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
"TEXTAREA",
"INPUT",
"SELECT",
"BUTTON",
]);
const _ready = (callback) => {
if (document.readyState !== "loading") {
callback();
} else {
document.addEventListener("DOMContentLoaded", callback);
2021-05-16 21:40:49 +00:00
}
};
/**
* Small JavaScript module for the documentation.
*/
2022-09-29 22:02:15 +00:00
const Documentation = {
init: () => {
Documentation.initDomainIndexTable();
Documentation.initOnKeyListeners();
2021-05-16 21:40:49 +00:00
},
/**
* i18n support
*/
2022-09-29 22:02:15 +00:00
TRANSLATIONS: {},
PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
LOCALE: "unknown",
2021-05-16 21:40:49 +00:00
// gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext)
2022-09-29 22:02:15 +00:00
gettext: (string) => {
const translated = Documentation.TRANSLATIONS[string];
switch (typeof translated) {
case "undefined":
return string; // no translation
case "string":
return translated; // translation exists
default:
return translated[0]; // (singular, plural) translation tuple exists
}
2021-05-16 21:40:49 +00:00
},
2022-09-29 22:02:15 +00:00
ngettext: (singular, plural, n) => {
const translated = Documentation.TRANSLATIONS[singular];
if (typeof translated !== "undefined")
return translated[Documentation.PLURAL_EXPR(n)];
return n === 1 ? singular : plural;
2021-05-16 21:40:49 +00:00
},
2022-09-29 22:02:15 +00:00
addTranslations: (catalog) => {
Object.assign(Documentation.TRANSLATIONS, catalog.messages);
Documentation.PLURAL_EXPR = new Function(
"n",
`return (${catalog.plural_expr})`
);
Documentation.LOCALE = catalog.locale;
2021-05-16 21:40:49 +00:00
},
/**
2022-09-29 22:02:15 +00:00
* helper function to focus on search bar
2021-05-16 21:40:49 +00:00
*/
2022-09-29 22:02:15 +00:00
focusSearchBar: () => {
document.querySelectorAll("input[name=q]")[0]?.focus();
2021-05-16 21:40:49 +00:00
},
/**
2022-09-29 22:02:15 +00:00
* Initialise the domain index toggle buttons
2021-05-16 21:40:49 +00:00
*/
2022-09-29 22:02:15 +00:00
initDomainIndexTable: () => {
const toggler = (el) => {
const idNumber = el.id.substr(7);
const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
if (el.src.substr(-9) === "minus.png") {
el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
toggledRows.forEach((el) => (el.style.display = "none"));
} else {
el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
toggledRows.forEach((el) => (el.style.display = ""));
2021-05-16 21:40:49 +00:00
}
2022-09-29 22:02:15 +00:00
};
2021-05-16 21:40:49 +00:00
2022-09-29 22:02:15 +00:00
const togglerElements = document.querySelectorAll("img.toggler");
togglerElements.forEach((el) =>
el.addEventListener("click", (event) => toggler(event.currentTarget))
);
togglerElements.forEach((el) => (el.style.display = ""));
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
2021-05-16 21:40:49 +00:00
},
2022-09-29 22:02:15 +00:00
initOnKeyListeners: () => {
// only install a listener if it is really needed
if (
!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
)
return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
// bail with special keys
if (event.altKey || event.ctrlKey || event.metaKey) return;
if (!event.shiftKey) {
switch (event.key) {
case "ArrowLeft":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const prevLink = document.querySelector('link[rel="prev"]');
if (prevLink && prevLink.href) {
window.location.href = prevLink.href;
event.preventDefault();
2021-05-16 21:40:49 +00:00
}
2022-09-29 22:02:15 +00:00
break;
case "ArrowRight":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const nextLink = document.querySelector('link[rel="next"]');
if (nextLink && nextLink.href) {
window.location.href = nextLink.href;
event.preventDefault();
2021-05-16 21:40:49 +00:00
}
2022-09-29 22:02:15 +00:00
break;
2021-05-16 21:40:49 +00:00
}
}
2022-09-29 22:02:15 +00:00
// some keyboard layouts may need Shift to get /
switch (event.key) {
case "/":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.focusSearchBar();
event.preventDefault();
}
2021-05-16 21:40:49 +00:00
});
2022-09-29 22:02:15 +00:00
},
2021-05-16 21:40:49 +00:00
};
// quick alias for translations
2022-09-29 22:02:15 +00:00
const _ = Documentation.gettext;
2021-05-16 21:40:49 +00:00
2022-09-29 22:02:15 +00:00
_ready(Documentation.init);