',
"CONFIG": '{% set icon = config.theme.icon.alternate or "material/translate" %}',
"SELECTOR": '{% include ".icons/" ~ icon ~ ".svg" %}',
"LINK": "{{ alt.name }}",
- "END": "{% endif %}",
+ "END": "
",
}
# A negative number means the same level as the START token.
end_indent_level: int = -1
- # Open the file and load the section
- with open(partial, encoding="utf8") as file:
- loaded_content: str = file.read()
+ override_manager = config.extra[HOOK_MANAGER]
- loaded_section: str = _load_section(
- content=loaded_content,
+ loaded_section: str = override_manager.load_section(
+ partial=partial,
tokens=tokens,
end_level=end_indent_level,
- file_name=partial.name,
)
# Do not continue when section is not loaded
if not loaded_section:
return
- # Do not continue when section is not valid (due to some update or another hook)
- if not _is_section_valid(tokens=tokens, loaded_section=loaded_section, file_name=partial.name):
- return
-
# Load all flags relevant to the current build
flag_mapping: Dict[str, str] = {
alt["lang"]: _flag_svg(alt["lang"]) for alt in config["extra"]["alternate"]
}
# Set the "flag_mapping" selector
- selector: str = "config.theme.language"
+ # Choose different selector for the "i18n" plugin
+ selector: str = "i18n_page_locale" if "i18n" in config.plugins else "config.theme.language"
- # Change selector for the "i18n" plugin
- if "i18n" in config.plugins:
- selector = "i18n_page_locale"
-
- # Modify the partial
- with open(partial, "w", encoding="utf8") as file:
- file.write(
- loaded_content.replace(
- loaded_section,
- loaded_section.replace(
- tokens["CONFIG"], "{% set flag_mapping = " + str(flag_mapping) + " %}"
- )
- .replace(tokens["SELECTOR"], "{{ flag_mapping[" + selector + "] }}")
- .replace(
- tokens["LINK"],
- "{{ flag_mapping[alt.lang] }} "
- + '{{ alt.name | replace(alt.lang, "") | replace(" ", "") | replace("-", "") }}',
- ),
- )
+ modified_section: str = (
+ loaded_section.replace(
+ tokens["CONFIG"], "{% set flag_mapping = " + str(flag_mapping) + " %}"
)
+ .replace(tokens["SELECTOR"], "{{ flag_mapping[" + selector + "] }}")
+ .replace(
+ tokens["LINK"],
+ "{{ flag_mapping[alt.lang] }} "
+ + '{{ alt.name | replace(alt.lang, "") | replace(" ", "") | replace("-", "") }}',
+ )
+ )
- LOG.debug(f'{HOOK_NAME}: Processed "{partial.name}".')
-
-
-def _load_section(*, content: str, tokens: Dict[str, str], end_level: int, file_name: str) -> str:
- """Load the section from the content"""
-
- lines: List[str] = []
- section_started: bool = False
- section_ended: bool = False
-
- for line in content.split("\n"):
- if tokens["START"] in line:
- section_started = True
- if end_level < 0:
- end_level = len(line) - len(line.lstrip())
-
- if section_started:
- lines.append(line)
- if tokens["END"] in line and (len(line) - len(line.lstrip())) == end_level:
- section_ended = True
- break
-
- if not section_ended or not section_started:
- message: str = "started" if not section_started else "ended"
- LOG.error(f'{HOOK_NAME}: Section in file "{file_name}" never {message}')
- _write_log("\n".join(lines), f"{HOOK_NAME}_read_error.html")
- return ""
-
- return "\n".join(lines)
-
-
-def _is_section_valid(*, tokens: Dict[str, str], loaded_section: str, file_name: str) -> bool:
- """Validate that the loaded section contains all tokens"""
-
- try:
- for value in tokens.values():
- assert value in loaded_section
- except AssertionError:
- LOG.error(f'{HOOK_NAME}: Section mismatch in "{file_name}"')
- _write_log(loaded_section, f"{HOOK_NAME}_mismatch.html")
- return False
+ # Modify the partial
+ override_manager.save_section(
+ partial=partial, original_section=loaded_section, modified_section=modified_section
+ )
- return True
+ LOG.debug(f'Processed "{partial.name}".')
def _flag_svg(alternate_lang: str) -> str:
@@ -328,41 +144,8 @@ def _flag_svg(alternate_lang: str) -> str:
return f'
'
-def _write_log(content: str, file_name: str) -> None:
- """Write `content` to TEMP_DIR/`file_name`"""
- crash_log = Path(tempfile.gettempdir()) / file_name
- with open(crash_log, "w", encoding="utf8") as file:
- file.write(content)
- LOG.info(f'{HOOK_NAME}: File saved "{crash_log}"')
-
-
# endregion
-# region Closing Events
-
-
-def on_build_error(*_, **__) -> None:
- """Restores backup. Triggers when the build errors, safety measure if "on_shutdown" won't trigger."""
-
- LOG.debug(f'{HOOK_NAME}: Running "on_build_error"')
- BackupManager.restore_backup()
-
-
-def on_post_build(*_, **__) -> None:
- """Restores backup. Triggers when a build finishes."""
-
- LOG.debug(f'{HOOK_NAME}: Running "on_post_build"')
- BackupManager.restore_backup()
-
-
-def on_shutdown(*_, **__) -> None:
- """Restores backup. Triggers when MkDocs terminates."""
-
- LOG.debug(f'{HOOK_NAME}: Running "on_shutdown"')
- BackupManager.restore_backup()
-
-
-# endregion
# region Constants
@@ -433,8 +216,8 @@ def on_shutdown(*_, **__) -> None:
HOOK_NAME: str = "language_flags"
"""Name of this hook. Used in logging."""
-HOOK_NAMESPACE: str = "material_override_hooks"
-"""Namespace of this hook. Used for storing data shared between hooks."""
+HOOK_MANAGER: str = "theme_overrides_manager"
+"""Name of the hook manager. Used to access it in `config.extra`."""
INDEX: Dict[str, Union[str, Dict]] = {
"name": "twemoji",
@@ -445,7 +228,9 @@ def on_shutdown(*_, **__) -> None:
# Adapted from
# materialx.emoji
-LOG: logging.Logger = logging.getLogger(f"mkdocs.hooks.{HOOK_NAME}")
+LOG: PrefixedLogger = PrefixedLogger(
+ HOOK_NAME, logging.getLogger(f"mkdocs.hooks.theme_overrides.{HOOK_NAME}")
+)
"""Logger instance for this hook."""
# endregion
diff --git a/overrides/.hooks/preferences.py b/overrides/.hooks/preferences.py
new file mode 100644
index 0000000000..021e13369c
--- /dev/null
+++ b/overrides/.hooks/preferences.py
@@ -0,0 +1,38 @@
+"""Hook that manages the preferences.md page, primarily i18n dynamics.
+"""
+import re
+
+from mkdocs import plugins
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+
+@plugins.event_priority(100)
+def on_page_markdown(
+ markdown: str, /, *, page: Page, config: MkDocsConfig, files: Files
+) -> str | None:
+ if "preferences_i18n" not in page.meta:
+ return markdown
+
+ default_lang_code: str = "en"
+ lang_code: str = (
+ config.theme["language"]
+ if config.theme["language"] in page.meta["preferences_i18n"]
+ else default_lang_code
+ )
+ current_i18n: dict[str, str] = {
+ **page.meta["preferences_i18n"][default_lang_code],
+ **page.meta["preferences_i18n"][lang_code],
+ }
+ tokens: list[str] = re.findall(r"\{\{.*?}}", markdown)
+
+ for token in tokens:
+ short_token = token.lstrip("{{").rstrip("}}").strip()
+ markdown = markdown.replace(token, current_i18n[short_token])
+
+ # print(1, lang_code)
+ # print(2, current_i18n)
+ # print(3, tokens)
+
+ return markdown
diff --git a/overrides/.hooks/theme_overrides_manager.py b/overrides/.hooks/theme_overrides_manager.py
new file mode 100644
index 0000000000..2b3e337631
--- /dev/null
+++ b/overrides/.hooks/theme_overrides_manager.py
@@ -0,0 +1,279 @@
+"""MkDocs hook, which adds a backup and restore cycle for files that will be overriden.
+
+On its own it is not that useful. It acts as the manager for other hooks.
+It gathers all files from other hooks and triggers their functions.
+
+MIT Licence 2023 Kamil Krzyśków (HRY)
+"""
+import enum
+import filecmp
+import logging
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Set, Tuple
+
+import jinja2
+from mkdocs import plugins
+from mkdocs.config import Config
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import PrefixedLogger
+from mkdocs.structure.files import Files
+
+# region Core Logic Events
+
+
+@plugins.event_priority(100)
+def on_config(config: MkDocsConfig) -> Optional[Config]:
+ """Triggers just after the config loaded.
+
+ Initializes the ThemeOverridesManager class to pass data between hooks.
+ """
+
+ LOG.debug('Running "on_config"')
+
+ ThemeOverridesManager.initialize()
+ config.extra[HOOK_NAME] = ThemeOverridesManager
+
+ LOG.info("Theme overrides manager initialized")
+
+ return None
+
+
+@plugins.event_priority(-75)
+def on_env(
+ env: jinja2.Environment, *, config: MkDocsConfig, files: Files
+) -> Optional[jinja2.Environment]:
+ """Main function. Triggers just before the build begins."""
+
+ LOG.debug('Running "on_env"')
+
+ if not ThemeOverridesManager.all_paths_exist():
+ return None
+
+ if not ThemeOverridesManager.paths_with_processors:
+ LOG.info("No file processors were registered")
+ return None
+
+ ThemeOverridesManager.create_backup()
+
+ # Invoke each function with all available parameters
+ for path, func in ThemeOverridesManager.paths_with_processors:
+ func(partial=path, env=env, config=config, files=files)
+
+ return None
+
+
+# endregion
+
+# region Closing Events
+
+
+def on_build_error(*_, **__) -> None:
+ """Restores backup. Triggers when the build errors, safety measure if "on_shutdown" won't trigger."""
+
+ LOG.debug('Running "on_build_error"')
+
+ ThemeOverridesManager.restore_backup()
+
+
+def on_post_build(*_, **__) -> None:
+ """Restores backup. Triggers when a build finishes."""
+
+ LOG.debug('Running "on_post_build"')
+
+ ThemeOverridesManager.restore_backup()
+
+
+def on_shutdown(*_, **__) -> None:
+ """Restores backup. Triggers when MkDocs terminates."""
+
+ LOG.debug('Running "on_shutdown"')
+
+ ThemeOverridesManager.restore_backup()
+
+
+# endregion
+
+
+# region Backup Management Class
+
+
+class BackupState(enum.IntEnum):
+ """Possible states for the backup process"""
+
+ NONE: int = 10
+ """None backups exist"""
+
+ CREATED: int = 20
+ """All backups exist"""
+
+
+class ThemeOverridesManager:
+ """Helper class, which handles the backing up of files"""
+
+ def __init__(self):
+ raise NotImplementedError("This class should have no instances.")
+
+ @classmethod
+ def initialize(cls):
+ cls.backup_state = BackupState.NONE
+ cls.sources = set()
+ cls.paths_with_processors = []
+
+ @classmethod
+ def all_paths_exist(cls) -> bool:
+ """Checks if the provided source paths exist"""
+
+ result = True
+
+ for src, _ in cls.paths_with_processors:
+ if not src.exists():
+ LOG.error(f"File doesn't exist {src}")
+ result = False
+
+ return result
+
+ @classmethod
+ def create_backup(cls) -> None:
+ """Creates backup files with ".backup" suffix within the same directory as the source file."""
+
+ for src, _ in cls.paths_with_processors:
+ cls.sources.add(src)
+
+ backup_len: int = len(cls.sources)
+
+ LOG.info(f'Backing up {backup_len} file{"" if backup_len == 1 else "s"}...')
+
+ for src in cls.sources:
+ backup: Path = Path(f"{src}.backup")
+ if backup.exists():
+ LOG.info(f'Found "{backup.name}" before creation, restoring...')
+ shutil.copy2(backup, src)
+ assert filecmp.cmp(backup, src, shallow=False)
+ continue
+
+ shutil.copy2(src, backup)
+ assert filecmp.cmp(src, backup, shallow=False)
+ LOG.debug(f'Created "{backup.name}"')
+
+ if backup_len > 0:
+ cls.backup_state = BackupState.CREATED
+
+ @classmethod
+ def restore_backup(cls) -> None:
+ """Restores backup files and deletes them after"""
+
+ if cls.backup_state != BackupState.CREATED:
+ return
+
+ backup_len: int = len(cls.sources)
+
+ LOG.info(f'Restoring {backup_len} file{"" if backup_len == 1 else "s"}...')
+ for src in cls.sources:
+ backup: Path = Path(f"{src}.backup")
+ if not backup.exists():
+ LOG.error(f'Backup "{backup.name}" doesn\'t exist')
+ continue
+
+ shutil.copy2(backup, src)
+ assert filecmp.cmp(backup, src, shallow=False)
+ backup.unlink()
+ LOG.debug(f'Restored "{src.name}"')
+
+ cls.backup_state = BackupState.NONE
+
+ @classmethod
+ def load_section(cls, *, partial: Path, tokens: Dict[str, str], end_level: int) -> str:
+ """Load the section for a given partial together with some validation"""
+
+ content: str = partial.read_text(encoding="utf8")
+ lines: List[str] = []
+ section_started: bool = False
+ section_ended: bool = False
+
+ for line in content.split("\n"):
+ if tokens["START"] in line:
+ section_started = True
+ if end_level < 0:
+ end_level = len(line) - len(line.lstrip())
+
+ if section_started:
+ lines.append(line)
+ if tokens["END"] in line and (len(line) - len(line.lstrip())) == end_level:
+ section_ended = True
+ break
+
+ loaded_section: str = "\n".join(lines)
+
+ # Validate that the loaded section started and ended
+ # Theme update, or another dynamic hook could have removed needed tokens
+ if not section_ended or not section_started:
+ message: str = "started" if not section_started else "ended"
+ LOG.error(f'Section in file "{partial.name}" never {message}')
+ cls.write_log(loaded_section, f"{partial.name}_read_error.html")
+ return ""
+
+ # Validate that the loaded section contains all tokens
+ # Theme update, or another dynamic hook could have removed needed tokens
+ try:
+ for value in tokens.values():
+ assert value in loaded_section
+ except AssertionError:
+ LOG.error(f'Section mismatch in "{partial.name}"')
+ log_content = ""
+ for value in tokens.values():
+ log_content += f"{value in loaded_section} - {value}\n"
+ cls.write_log(log_content + loaded_section, f"{partial.name}_mismatch.html")
+ return ""
+
+ return loaded_section
+
+ @classmethod
+ def save_section(cls, *, partial: Path, original_section: str, modified_section: str) -> None:
+ """Save partial with modified section"""
+
+ content: str = partial.read_text(encoding="utf8")
+ partial.write_text(
+ data=content.replace(original_section, modified_section), encoding="utf8"
+ )
+
+ @classmethod
+ def write_log(cls, content: str, file_name: str) -> None:
+ """Write `content` to TEMP_DIR/`file_name`"""
+ crash_log = Path(tempfile.gettempdir()) / file_name
+ crash_log.write_text(data=content, encoding="utf8")
+ LOG.info(f'File saved "{crash_log}"')
+
+ backup_state: BackupState
+ """Status of the backup process"""
+
+ sources: Set[Path]
+ """Set of source file paths, which will be backed up."""
+
+ paths_with_processors: List[Tuple[Path, Callable]]
+ """List of tuple pairs of file paths and their processing functions.
+
+ Each function gets called with the following parameters in the `on_env` event:
+
+ - partial: pathlib.Path
+ - config: mkdocs.config.defaults.MkDocsConfig
+ - env: jinja2.Environment
+ - files: Files
+ """
+
+
+# endregion
+
+
+# region Constants
+
+HOOK_NAME: str = "theme_overrides_manager"
+"""Name of this hook. Used in logging."""
+
+LOG: PrefixedLogger = PrefixedLogger(
+ HOOK_NAME, logging.getLogger("mkdocs.hooks.theme_overrides.__main__")
+)
+"""Logger instance for this hook."""
+
+# endregion
diff --git a/overrides/assets/icons/spacer-bool.png b/overrides/assets/icons/spacer-bool.png
new file mode 100644
index 0000000000..693a514bfc
Binary files /dev/null and b/overrides/assets/icons/spacer-bool.png differ
diff --git a/overrides/assets/icons/spacer-class.png b/overrides/assets/icons/spacer-class.png
new file mode 100644
index 0000000000..71a64637b5
Binary files /dev/null and b/overrides/assets/icons/spacer-class.png differ
diff --git a/overrides/assets/icons/spacer-color.png b/overrides/assets/icons/spacer-color.png
new file mode 100644
index 0000000000..efd9bf2514
Binary files /dev/null and b/overrides/assets/icons/spacer-color.png differ
diff --git a/overrides/assets/icons/spacer-enum.png b/overrides/assets/icons/spacer-enum.png
new file mode 100644
index 0000000000..86871d444a
Binary files /dev/null and b/overrides/assets/icons/spacer-enum.png differ
diff --git a/overrides/assets/icons/spacer-float.png b/overrides/assets/icons/spacer-float.png
new file mode 100644
index 0000000000..18278ed923
Binary files /dev/null and b/overrides/assets/icons/spacer-float.png differ
diff --git a/overrides/assets/icons/spacer-folder.png b/overrides/assets/icons/spacer-folder.png
new file mode 100644
index 0000000000..6a1236d820
Binary files /dev/null and b/overrides/assets/icons/spacer-folder.png differ
diff --git a/overrides/assets/icons/spacer-int.png b/overrides/assets/icons/spacer-int.png
new file mode 100644
index 0000000000..beb3f0bea8
Binary files /dev/null and b/overrides/assets/icons/spacer-int.png differ
diff --git a/overrides/assets/icons/spacer-misc.png b/overrides/assets/icons/spacer-misc.png
new file mode 100644
index 0000000000..f03426fcce
Binary files /dev/null and b/overrides/assets/icons/spacer-misc.png differ
diff --git a/overrides/assets/icons/spacer-string.png b/overrides/assets/icons/spacer-string.png
new file mode 100644
index 0000000000..7c6f70fbb3
Binary files /dev/null and b/overrides/assets/icons/spacer-string.png differ
diff --git a/overrides/assets/icons/spacer-vec.png b/overrides/assets/icons/spacer-vec.png
new file mode 100644
index 0000000000..0f88b1d306
Binary files /dev/null and b/overrides/assets/icons/spacer-vec.png differ
diff --git a/overrides/assets/images/c_menu_item_farmesize.png b/overrides/assets/images/c_menu_item_farmesize.png
new file mode 100644
index 0000000000..b2769a5c28
Binary files /dev/null and b/overrides/assets/images/c_menu_item_farmesize.png differ
diff --git a/overrides/assets/images/union_sdk_getting_started_messagebox.png b/overrides/assets/images/union_sdk_getting_started_messagebox.png
new file mode 100644
index 0000000000..481b1c0b86
Binary files /dev/null and b/overrides/assets/images/union_sdk_getting_started_messagebox.png differ
diff --git a/overrides/assets/images/zSpy.png b/overrides/assets/images/zSpy.png
new file mode 100644
index 0000000000..7c3d4cbe92
Binary files /dev/null and b/overrides/assets/images/zSpy.png differ
diff --git a/overrides/assets/javascripts/extra.js b/overrides/assets/javascripts/extra.js
index bba6dbf750..1687025f2e 100644
--- a/overrides/assets/javascripts/extra.js
+++ b/overrides/assets/javascripts/extra.js
@@ -100,13 +100,18 @@ window.addEventListener("DOMContentLoaded", _ => {
gmcExpandNavigation();
gmcAddVersionToggle();
gmcLinksForVersion();
- if (gGMC_PAGE_LOCALE !== gGMC_DEFAULT_LOCALE && gGMC_PAGE_LOCALE !== gGMC_PAGE_FILE_LOCALE) {
+ if (gGMC_PAGE_LOCALE !== gGMC_DEFAULT_LOCALE
+ && gGMC_PAGE_LOCALE !== gGMC_FILE_LOCALE
+ && !gGMC_REMOVE_TRANSLATION_PROMPTS) {
gmcTranslateButton();
}
gmcRemoveCodeLines();
gmcExternalLinks();
- new gMutationObserver(gmcSearchMutationCallback)
- .observe(document.querySelector(".md-search-result__list"), {childList: true});
+ const searchResults = document.querySelector(".md-search-result__list");
+ if (searchResults) {
+ new gMutationObserver(gmcSearchMutationCallback)
+ .observe(searchResults, {childList: true});
+ }
});
window.addEventListener("hashchange", _ => {
@@ -155,17 +160,19 @@ function gmcExpandNavigation() {
return;
}
- const activeLink = document.querySelector(".md-nav__link--active");
+ const activeLinkLabel = document.querySelector("label.md-nav__link--active");
- if (!activeLink) {
+ if (!activeLinkLabel) {
return;
}
- let activeNav = activeLink.parentElement.querySelector("nav");
+ const navID = activeLinkLabel.id;
+
+ let activeNav = document.querySelector(`nav[aria-labelledby="${navID}"]`);
if (!activeNav || activeNav.className.includes("md-nav--secondary")) {
- // gmcDebug(`nav not foundInParent`);
- activeNav = activeLink.closest("nav");
+ // gmcDebug(`nav with id ${navID} not found`);
+ activeNav = activeLinkLabel.closest("nav");
}
if (activeNav.dataset.hasOwnProperty("mdLevel")) {
@@ -402,6 +409,7 @@ const gmcTranslateButton = () => {
"*GitHub's file editor doesn't provide `.md` formatting options, if you want those, consider using https://stackedit.io/*",
].join(" \n"));
const newAnchor = document.createElement("a");
+ newAnchor.id = "gmc-new-translation-button";
newAnchor.classList = anchor.classList;
// Weird quirk. The topDirectory needs to be in both, the link and in the filename param to put the file in the correct directory.
// -- This quirk stopped quirking with the introduction of the new GitHub UI, sadge.
@@ -409,7 +417,7 @@ const gmcTranslateButton = () => {
newAnchor.innerHTML = gGMC_TRANSLATE_SVG;
newAnchor.title = gGMC_TRANSLATE_CTA;
anchor.parentElement.prepend(newAnchor);
-}
+};
const gmcRemoveCodeLines = () => {
const nodesForRemoval = [];
@@ -426,13 +434,14 @@ const gmcRemoveCodeLines = () => {
};
const gmcFadingNavigation = () => {
- const activeNavItems = document.querySelectorAll(".md-nav__item--active");
+ const activeNavItems = document.querySelectorAll(".md-nav__item--active.md-nav__item--nested");
if (activeNavItems.length <= 1)
return;
activeNavItems[0].classList.add("gmc-fade-nav");
-}
+ activeNavItems[activeNavItems.length - 1].classList.add("gmc-fade-nav-off");
+};
function gmcDebug(...message) {
if (gGMC_LOCAL)
diff --git a/overrides/assets/javascripts/preferences.js b/overrides/assets/javascripts/preferences.js
new file mode 100644
index 0000000000..964c5fdb5d
--- /dev/null
+++ b/overrides/assets/javascripts/preferences.js
@@ -0,0 +1,253 @@
+/*
+ * Licence MIT - Copyright (c) 2024 Kamil Krzyśków (HRY)
+ */
+
+const gmcPreferenceHandler = (event) => {
+ console.debug(event);
+ const target = event.target;
+ const option = target.dataset["option"];
+ // preferencesKey defined in extrahead template override
+ let loadedPreferences = __md_get(preferencesKey);
+ if (!loadedPreferences[option]) {
+ loadedPreferences[option] = {};
+ }
+
+ // TODO reconsider the OOP approach idea
+ const optionHandlers = {
+ "color": updateColorPreference,
+ "custom": () => {
+ loadedPreferences[option]["cssRaw"] = target.value;
+ },
+ "font": updateFontPreference,
+ };
+
+ if (optionHandlers[option]) {
+ optionHandlers[option](option, target, loadedPreferences);
+ } else {
+ console.error("Unhandled option", option, target.value);
+ }
+
+ updateGlobalPreferences(loadedPreferences);
+ __md_set(preferencesKey, loadedPreferences);
+ // Function defined in extrahead template override
+ gmcLoadSetPreferences();
+};
+
+const updateColorPreference = (option, target, loadedPreferences) => {
+ const extra = target.dataset["extra"];
+ const handle = loadedPreferences[option];
+ if (extra === "reset") {
+ loadedPreferences[option] = {};
+ document.querySelector(`#preference-color-accent`).value = "#000000";
+ document.querySelector(`#preference-color-hue`).value = "#000000";
+ return;
+ }
+ // Credit: https://stackoverflow.com/questions/3732046/how-do-you-get-the-hue-of-a-xxxxxx-colour
+ const hexColor = target.value;
+ const red = parseInt(hexColor.substr(1, 2), 16);
+ const green = parseInt(hexColor.substr(3, 2), 16);
+ const blue = parseInt(hexColor.substr(5, 2), 16);
+ let [hue, _, lightness] = rgbToHsl(red, green, blue);
+ hue = Math.floor(hue * 360);
+ lightness = Math.round(lightness * 240);
+
+ const mod = 20;
+ const redDarkerHex = Math.max(red - mod, 0).toString(16).padStart(2, "0");
+ const greenDarkerHex = Math.max(green - mod, 0).toString(16).padStart(2, "0");
+ const blueDarkerHex = Math.max(blue - mod, 0).toString(16).padStart(2, "0");
+ const darkerColorHex = `#${redDarkerHex}${greenDarkerHex}${blueDarkerHex}`;
+
+ if (!handle[extra]) {
+ handle[extra] = {};
+ }
+
+ handle[extra]["value"] = target.value;
+ if (extra === "hue") {
+ handle[extra]["calculatedHue"] = hue;
+ } else if (extra === "accent") {
+ handle[extra]["darker"] = darkerColorHex;
+ handle[extra]["calculatedHue"] = hue;
+ }
+
+ handle["cssRaw"] = "*, :before, :after { ";
+ if (handle["hue"]) {
+ handle["cssRaw"] += `--md-hue: ${handle["hue"]["calculatedHue"]}deg;`;
+ }
+ if (handle["accent"]) {
+ handle["cssRaw"] += `--gmc-tabs-bg-hue: ${handle["accent"]["calculatedHue"]}deg;`;
+ handle["cssRaw"] += `--md-accent-fg-color: ${handle["accent"]["value"]};`;
+ handle["cssRaw"] += `--md-accent-fg-color--transparent: ${handle["accent"]["value"]}1a;`;
+ handle["cssRaw"] += `--md-typeset-a-color: ${handle["accent"]["darker"]};`
+ if (lightness > 120) {
+ handle["cssRaw"] += "--md-accent-bg-color: #000000de;";
+ handle["cssRaw"] += "--md-accent-bg-color--light: #0000008a;"
+ } else {
+ handle["cssRaw"] += "--md-accent-bg-color: #fff;";
+ handle["cssRaw"] += "--md-accent-bg-color--light: #ffffffb3;"
+ }
+ }
+ handle["cssRaw"] += " }\n";
+}
+
+const updateFontPreference = (option, target, loadedPreferences) => {
+ const handle = loadedPreferences[option];
+ handle["value"] = target.value;
+ handle["cssRaw"] = "";
+
+ if (target.value === "opendyslexic") {
+ // Due to the JavaScript CSS injection -> Import Fetch there is a delay
+ // when it comes to enabling the custom font. The default font flashes for a second or 2.
+ // Only fix for this would be to remove the import and inject the CSS font file directly,
+ // however that is not ideal either.
+ handle["cssRaw"] += `@import url('https://fonts.cdnfonts.com/css/opendyslexic');
+ :root { --md-text-font: "OpenDyslexic"; --md-code-font: "OpenDyslexicMono"; }`;
+ }
+ // Initial attempt that didn't work due to CORS, but is valid for adding CSS based on the font URLs.
+ // Doesn't handle TTF or OTF fonts, only WOFF/2.
+ // if (target.value === "opendyslexic") {
+ // const fontUrls = [
+ // "https://github.com/antijingoist/opendyslexic/raw/master/compiled/OpenDyslexic-Regular.woff2",
+ // "https://github.com/antijingoist/opendyslexic/raw/master/compiled/OpenDyslexic-Italic.woff2",
+ // "https://github.com/antijingoist/opendyslexic/raw/master/compiled/OpenDyslexic-Bold.woff",
+ // "https://github.com/antijingoist/opendyslexic/raw/master/compiled/OpenDyslexic-Bold-Italic.woff2",
+ // ];
+ // for (const url of fontUrls) {
+ // const fileName = url.split("/").pop();
+ // const fontName = fileName.split("-")[0];
+ // const formatName = fileName.split(".").pop();
+ // let currentFont = `@font-face { font-family: "${fontName}"; `;
+ // if (fontName.toLowerCase().includes("bold")) {
+ // currentFont += "font-weight: bold; ";
+ // }
+ // if (fontName.toLowerCase().includes("bold")) {
+ // currentFont += "font-style: italic; ";
+ // }
+ // currentFont += `src: local("${fontName}"), url("${url}") format("${formatName}"); }\n`
+ // handle["cssRaw"] += currentFont;
+ // }
+ // handle["cssRaw"] += ':root { --md-text-font: "OpenDyslexic"; }'
+ // }
+}
+
+const updateGlobalPreferences = (loadedPreferences) => {
+ loadedPreferences["__global"]["cssRaw"] = "";
+
+ const imports = [];
+ for (let key in loadedPreferences) {
+ if (key === "__global" || !loadedPreferences[key]["cssRaw"]) continue;
+ const lines = loadedPreferences[key]["cssRaw"].split("\n");
+ for (const line of lines) {
+ if (line.includes("@import")) {
+ imports.push(line);
+ } else {
+ loadedPreferences["__global"]["cssRaw"] += line + "\n";
+ }
+ }
+ }
+
+ if (imports) {
+ loadedPreferences["__global"]["cssRaw"] = imports.join("\n") + "\n" + loadedPreferences["__global"]["cssRaw"];
+ }
+}
+
+/**
+ * Removes the translation prompts from the page.
+ * Mostly a quick hack for the GMC Preferences page.
+ * Once this function is used more than 3 times,
+ * it would be better to have a backend preprocessor solution.
+ */
+const removeRedundantTranslationIndicator = () => {
+ // TODO backend preprocessor solution
+ const itemsToRemove = [
+ document.querySelector("#gmc-new-translation-button"),
+ document.querySelector(".gmc-announce")
+ ];
+
+ for (const item of itemsToRemove) {
+ // console.debug(item);
+ if (item) {
+ item.remove();
+ }
+ }
+};
+
+/*
+ This is run immediately when loaded to limit UI elements flashing.
+*/
+(() => {
+
+ // Defined in extrahead template override
+ gGMC_REMOVE_TRANSLATION_PROMPTS = true;
+ removeRedundantTranslationIndicator();
+
+ const loadedPreferences = __md_get(preferencesKey);
+ const options = ["color-accent", "color-hue", "color-reset", "font", "custom"];
+
+ for (const option of options) {
+ const el = document.querySelector(`#preference-${option}`);
+ const split = option.split("-");
+ const handle = loadedPreferences[option];
+ if (handle) {
+ const value = handle["value"] || handle["cssRaw"];
+ if (value) {
+ el.value = value;
+ }
+ } else if (split.length === 2 && loadedPreferences[split[0]] && loadedPreferences[split[0]][split[1]]) {
+ const value = loadedPreferences[split[0]][split[1]]["value"];
+ if (value) {
+ el.value = value;
+ }
+ }
+ if (el.tagName.toLowerCase() === "a") {
+ el.addEventListener("click", gmcPreferenceHandler);
+ } else {
+ el.addEventListener("change", gmcPreferenceHandler);
+ }
+ }
+
+})();
+
+/**
+ * Converts an RGB color value to HSL. Conversion formula
+ * adapted from http://en.wikipedia.org/wiki/HSL_color_space.
+ * Assumes r, g, and b are contained in the set [0, 255] and
+ * returns h, s, and l in the set [0, 1].
+ *
+ * Credit: https://gist.github.com/mjackson/5311256
+ *
+ * @return Array The HSL representation
+ * @param r
+ * @param g
+ * @param b
+ */
+function rgbToHsl(r, g, b) {
+ r /= 255;
+ g /= 255;
+ b /= 255;
+
+ const max = Math.max(r, g, b), min = Math.min(r, g, b);
+ let h, s, l = (max + min) / 2;
+
+ if (max === min) {
+ h = s = 0; // achromatic
+ } else {
+ const d = max - min;
+ s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+ switch (max) {
+ case r:
+ h = (g - b) / d + (g < b ? 6 : 0);
+ break;
+ case g:
+ h = (b - r) / d + 2;
+ break;
+ case b:
+ h = (r - g) / d + 4;
+ break;
+ }
+
+ h /= 6;
+ }
+
+ return [h, s, l];
+}
\ No newline at end of file
diff --git a/overrides/assets/stylesheets/constants.css b/overrides/assets/stylesheets/constants.css
index 0fa956a1b4..a959467188 100644
--- a/overrides/assets/stylesheets/constants.css
+++ b/overrides/assets/stylesheets/constants.css
@@ -8,4 +8,10 @@
--gmc-external-svg: url('data:image/svg+xml;charset=utf-8,');
/* SVG to CSS inline data converter: https://yoksel.github.io/url-encoder/ - output edited */
--md-admonition-icon--trivia: url('data:image/svg+xml;charset=utf-8,');
+}
+
+/* Color */
+:root {
+ --gmc-blue-tint: #00aafc;
+ --gmc-tabs-bg-hue: 210deg;
}
\ No newline at end of file
diff --git a/overrides/assets/stylesheets/extra.css b/overrides/assets/stylesheets/extra.css
index 257ede8386..97137b63f8 100644
--- a/overrides/assets/stylesheets/extra.css
+++ b/overrides/assets/stylesheets/extra.css
@@ -5,13 +5,14 @@
/* Add opacity to the less important parts of the page */
/* Adapted from https://github.com/AhmedThahir/Uni_Notes/blob/f3a59864f77d7a52d3e21e1007f9cd5c50ab5c66/docs/stylesheets/custom.css#L28-L44 */
@media screen and (min-width: 76.1875em) and (orientation: landscape) {
+ .md-nav--primary :is(.dummy-for-compressor) { display: none }
+
.md-nav--primary :is(a, label) {
will-change: opacity;
transition: opacity 0.4s !important;
}
- .gmc-fade-nav li:not(li:has(.md-nav__link--active), .md-nav--primary:hover li) :is(a, label)
- {
+ .gmc-fade-nav li:not(li:has(.md-nav__link--active), .md-nav--primary:hover li, .gmc-fade-nav-off li) :is(a, label) {
opacity: 0.2;
}
}
@@ -22,6 +23,18 @@
max-width: 75rem;
}
+/* override md-main on the page */
+@media screen {
+ [data-md-color-scheme=slate] {
+ --md-default-fg-color: hsla(var(--md-hue), 15%, 90%, 1);
+ }
+}
+
+/* Add left padding indent to the content */
+article > div > :is(:not(h1, h2, h3, h4)) {
+ padding-left: 1em !important;
+}
+
/* Shrink header and footer to the content size*/
.md-grid {
/* Default 61rem */
@@ -95,7 +108,7 @@ div.md-nav__link--index {
--md-accent-fg-color: #0b65b0;
}
[data-md-color-scheme=slate] {
- --md-accent-fg-color: #00aafc;
+ --md-accent-fg-color: var(--gmc-blue-tint);
}
}
@@ -109,6 +122,7 @@ div.md-nav__link--index {
.md-typeset :is(h1, h2, h3, h4, h5, h6) {
font-weight: 700;
color: var(--md-default-fg-color--light);
+ text-shadow: 0 0 0 var(--md-default-fg-color--light);
}
.md-typeset :is(h3, h4, h5, h6) {
@@ -124,9 +138,7 @@ div.md-nav__link--index {
}
@media {
- [data-md-color-scheme=slate] :is(.dummy-for-compressor) {
- display: none;
- }
+ [data-md-color-scheme=slate] :is(.dummy-for-compressor) { display: none }
/*--md-default-fg-color--light:hsla(var(--md-hue),75%,90%,0.62);*/
[data-md-color-scheme=slate] :is(h1, h2, h3, h4, h5, h6) {
--md-default-fg-color--light: hsla(var(--md-hue), 100%, 100%, 1);
@@ -171,16 +183,13 @@ div.md-nav__link--index {
/* override tabs navigation */
@media {
[data-md-color-scheme="slate"] .md-header {
- border-bottom: 0.10rem solid var(--md-accent-fg-color);
+ outline: .10rem solid var(--md-accent-fg-color);
}
- [data-md-color-scheme="slate"] .md-tabs__link--active {
+ [data-md-color-scheme="slate"] .md-tabs__item--active a.md-tabs__link {
color: var(--md-accent-fg-color);
}
- [data-md-color-scheme="default"] .md-header {
- border-bottom: 0.10rem solid #000;
- }
[data-md-color-scheme="slate"] .md-tabs {
- background-color: hsla(210, 100%, 20%, 1) !important;
+ background-color: hsla(var(--gmc-tabs-bg-hue), 100%, 20%, 1);
}
}
diff --git a/overrides/main.html b/overrides/main.html
index a6a6e8e9ce..31b35c35d5 100644
--- a/overrides/main.html
+++ b/overrides/main.html
@@ -1,5 +1,37 @@
{% extends "base.html" %}
+{% block extrahead %}
+ {{ super() }}
+
+{% endblock %}
+
{#
Extend the last block in the `base.html` before the changes are applicable
to avoid any issues with the hacky page.meta
@@ -9,14 +41,11 @@
{{ super() }}
{% if page %}
{% if not page.meta %}
- {# Set page.meta to a hacky reference of the page itself #}
- {% set _ = page.__setattr__("meta", page) %}
- {# Let It Snow by setting the page object attribute #}
- {% set _ = page.meta.__setattr__("ᴴₒᴴₒᴴₒ", True) %}
- {% else %}
- {# Let It Snow by updating the dict/mapping pair #}
- {% set _ = page.meta.update({"ᴴₒᴴₒᴴₒ": True}) %}
+ {# Set page.meta to an empty dict/mapping #}
+ {% set _ = page.__setattr__("meta", {}) %}
{% endif %}
+ {# Let It Snow by updating the dict/mapping pair #}
+ {% set _ = page.meta.update({"ᴴₒᴴₒᴴₒ": True}) %}
{% endif %}
{% endblock %}
@@ -35,7 +64,7 @@
"cs": "Podpoř nás a pomoz nám s překladem!",
}
%}
- {% if i18n_page_locale != "en" and i18n_page_file_locale != i18n_page_locale %}
+ {% if i18n_page_locale != "en" and i18n_file_locale != i18n_page_locale %}
{{ announcement[i18n_page_locale] }}
{{ call_to_action[i18n_page_locale] }}
@@ -46,7 +75,7 @@
const gGMC_SELECT_VERSION = "{{ lang.t('select.version') }}";
const gGMC_TRANSLATE_CTA = "{{ call_to_action[i18n_page_locale] }}";
const gGMC_PAGE_LOCALE = "{{ i18n_page_locale }}";
- const gGMC_PAGE_FILE_LOCALE = "{{ i18n_page_file_locale }}";
+ const gGMC_FILE_LOCALE = "{{ i18n_file_locale }}";
const gGMC_TRANSLATE_SVG = '{% include ".icons/material/web-plus.svg" %}';
{# Include original content after the additions #}
diff --git a/requirements-deploy.txt b/requirements-deploy.txt
new file mode 100644
index 0000000000..44368749d6
--- /dev/null
+++ b/requirements-deploy.txt
@@ -0,0 +1,4 @@
+# Deployment Requirements
+# Could be replaced with `pip install mkdocs-material[imaging]` in the future
+Pillow==10.1.0
+CairoSVG==2.7.1
diff --git a/requirements.txt b/requirements.txt
index a4b4283cb1..546b5cd34a 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,10 +1,10 @@
-mkdocs-material==9.1.5
-mkdocs-git-revision-date-localized-plugin==1.2.0
+# Core Requirements
+mkdocs-material==9.5.8
+mkdocs-git-revision-date-localized-plugin==1.2.1
mkdocs-video==1.5.0
-mkdocs-redirects==1.2.0
-mkdocs-minify-plugin==0.6.4
-# mkdocs-static-i18n==0.53
-git+https://github.com/kamilkrzyskow/i18n.git@920d38313b60812e8e03dba88a856bfdd41527dc#egg=mkdocs_static_i18n
+mkdocs-redirects==1.2.1
+mkdocs-minify-plugin==0.7.1
+mkdocs-static-i18n==1.2.0
git+https://github.com/kamilkrzyskow/gothic-lexer.git@b5ee7868a7e7397cd129ff1f847daa7d39c0e416#egg=gothic_lexer
-# mkdocs-awesome-pages-plugin==2.8.0
-git+https://github.com/kamilkrzyskow/awesome-pages.git@b0c544a92733977e09ac23c7f9238d13012f4fd9#egg=mkdocs_awesome_pages_plugin
\ No newline at end of file
+mkdocs-awesome-pages-plugin==2.9.2
+
diff --git a/tests/test_localization.py b/tests/test_localization.py
index 255fe4c43b..634d42734c 100644
--- a/tests/test_localization.py
+++ b/tests/test_localization.py
@@ -5,12 +5,12 @@
import json
import os
import unittest
+
import regex
# noinspection PyPackageRequirements
-import yaml
-
-from tests.path_constants import DOCS_DIR, OVERRIDES_DIR, ROOT_DIR
+from mkdocs.utils import yaml_load
+from path_constants import DOCS_DIR, OVERRIDES_DIR, ROOT_DIR
class LocalizationTest(unittest.TestCase):
@@ -19,18 +19,54 @@ class LocalizationTest(unittest.TestCase):
"""
config: dict = None
+ settings_to_check: list[tuple] = None
+ expected_settings: dict = None
@classmethod
def setUpClass(cls) -> None:
with open(os.path.join(ROOT_DIR, "mkdocs.yml"), encoding="utf8") as file:
- lines = file.readlines()
-
- # The default safe loader doesn't handle values containing !, they're not needed for localization
- # for the exception of !ENV which are important
- lines = [regex.sub(r"!ENV.*,\s*?(\w+)\]", r"\g<1>", line) for line in lines]
- output = "\n".join([regex.sub(r"!.*", "", line) for line in lines])
-
- for plugin in yaml.safe_load(output)["plugins"]:
+ content = file.read()
+
+ # Extract the ENV options, and assert that the selected boolean variables
+ # are set to the correct boolean values (aka weren't changed by mistake)
+ dirty_settings = regex.findall(r"\s*(.*?):\s*!ENV\s*\[(.*?)\]", content)
+ cls.settings_to_check = []
+
+ # Assure only controlled cases use undefined fallback values
+ allow_undefined = {
+ "GMC_DEV_LOCALE",
+ }
+
+ # some settings might have multiple !ENV toggles, so the catch all regex
+ # result needs to be cleaned up
+ for setting_group in dirty_settings:
+ if len(setting_group) != 2:
+ raise ValueError("Unhandled case setting_group isn't 2 values")
+
+ prop_name, envar = setting_group
+
+ fallback_value = None
+ splitted = list(map(str.strip, envar.split(",")))
+
+ if splitted[-1].lower() in {"true", "false"} or "'" in splitted[-1]:
+ fallback_value = eval(splitted.pop())
+
+ if fallback_value is None:
+ for var in splitted:
+ if var not in allow_undefined:
+ raise ValueError(
+ f"{prop_name} - {envar} should also define a default fallback"
+ )
+ else:
+ for var in splitted:
+ cls.settings_to_check.append((prop_name, var, fallback_value))
+
+ cls.expected_settings = {
+ "GMC_ENABLE_ON_PUBLISH": False,
+ "GMC_BUILD_ALTERNATES": False,
+ }
+
+ for plugin in yaml_load(content)["plugins"]:
if isinstance(plugin, dict):
cls.config = plugin.get("i18n")
if cls.config is not None:
@@ -38,28 +74,41 @@ def setUpClass(cls) -> None:
def setUp(self) -> None:
self.assertIsNot(self.config, None, msg="Localization config is None")
+ for setting_name, envar_name, actual in self.settings_to_check:
+ if envar_name not in self.expected_settings:
+ continue
+ expected = self.expected_settings[envar_name]
+ self.assertEqual(
+ actual,
+ expected,
+ msg=f"Setting '{setting_name}'->{envar_name} is set to {actual} instead of {expected}",
+ )
def test_default(self) -> None:
"""
Test that the default language is properly set, and that all languages are built
"""
default = "en"
- self.assertEqual(
- self.config["default_language"], default, msg=f"Default must be '{default}'"
- )
- self.assertTrue(
- default in self.config["languages"], msg=f"Language selector must contain '{default}'"
- )
- self.assertFalse(
- self.config["default_language_only"], msg=f"All languages must be deployed"
- )
+ default_present = False
+
+ for lang in self.config["languages"]:
+ lang_default = lang.get("default", False)
+ if lang["locale"] == default:
+ default_present = True
+ self.assertTrue(lang_default, msg=f"'{default}' must be set Default")
+ else:
+ self.assertFalse(lang_default, msg=f"Only '{default}' can be set Default")
+ self.assertTrue(
+ lang["build"], msg=f"All languages must be deployed - '{lang['locale']}' isn't"
+ )
+
+ self.assertTrue(default_present, msg=f"Language selector must contain '{default}'")
def test_announcement(self) -> None:
"""
Test that every localization has an announcement for untranslated content
"""
- languages = list(self.config["languages"].keys())
- languages.remove("en")
+ languages: list = self.config["languages"]
with open(os.path.join(OVERRIDES_DIR, "main.html"), encoding="utf8") as file:
main = file.read()
@@ -93,13 +142,14 @@ def test_announcement(self) -> None:
action = json.loads(regex.sub(r",\s*}", "}", regex.sub(r"\s+", " ", action_content)))
for language in languages:
+ locale = language["locale"]
self.assertTrue(
- language in announcement and language in action,
- msg=f"'{language}' is missing from at least one of the announcement dicts in main.html",
+ locale in announcement and locale in action,
+ msg=f"'{locale}' is missing from at least one of the announcement dicts in main.html",
)
self.assertTrue(
- len(announcement[language]) > 0 and len(action[language]) > 0,
- msg=f"'{language}' is empty in at least one of the announcement dicts in main.html",
+ len(announcement[locale]) > 0 and len(action[locale]) > 0,
+ msg=f"'{locale}' is empty in at least one of the announcement dicts in main.html",
)
def test_files(self) -> None: