From d39dee0bec25c825e0f37d7ef7a197cb2fb59d65 Mon Sep 17 00:00:00 2001 From: Wolf2323 Date: Mon, 2 Dec 2024 21:24:03 +0100 Subject: [PATCH] added default setup for docs --- docs/_custom_theme/.icons/brands/discord.svg | 9 ++ docs/_custom_theme/.icons/brands/mail.svg | 8 + docs/_custom_theme/externalLinkIcon.html | 25 +++ docs/_custom_theme/home.html | 148 ++++++++++++++++++ docs/_custom_theme/partials/toc-item.html | 38 +++++ docs/_custom_theme/partials/toc.html | 34 +++++ docs/_media/content/Home/waveDark.svg | 15 ++ docs/_media/content/Home/waveWhite.svg | 15 ++ docs/_webCode/css/button.css | 5 + docs/_webCode/css/centered.css | 7 + docs/_webCode/css/coloredIcons.css | 3 + docs/_webCode/css/contentAreaFullWidth.css | 3 + docs/_webCode/css/mermaidCentered.css | 3 + docs/_webCode/js/copyLinkToClipboard.js | 17 +++ docs/_webCode/js/copyrightYearUpdater.js | 6 + docs/_webCode/js/mathjax.js | 16 ++ docs/mkdocs_parent.yml | 153 +++++++++++++++++++ docs/setup-docs-dependencies.py | 29 ++++ 18 files changed, 534 insertions(+) create mode 100644 docs/_custom_theme/.icons/brands/discord.svg create mode 100644 docs/_custom_theme/.icons/brands/mail.svg create mode 100644 docs/_custom_theme/externalLinkIcon.html create mode 100644 docs/_custom_theme/home.html create mode 100644 docs/_custom_theme/partials/toc-item.html create mode 100644 docs/_custom_theme/partials/toc.html create mode 100644 docs/_media/content/Home/waveDark.svg create mode 100644 docs/_media/content/Home/waveWhite.svg create mode 100644 docs/_webCode/css/button.css create mode 100644 docs/_webCode/css/centered.css create mode 100644 docs/_webCode/css/coloredIcons.css create mode 100644 docs/_webCode/css/contentAreaFullWidth.css create mode 100644 docs/_webCode/css/mermaidCentered.css create mode 100644 docs/_webCode/js/copyLinkToClipboard.js create mode 100644 docs/_webCode/js/copyrightYearUpdater.js create mode 100644 docs/_webCode/js/mathjax.js create mode 100644 docs/mkdocs_parent.yml create mode 100644 docs/setup-docs-dependencies.py diff --git a/docs/_custom_theme/.icons/brands/discord.svg b/docs/_custom_theme/.icons/brands/discord.svg new file mode 100644 index 0000000..38ceae8 --- /dev/null +++ b/docs/_custom_theme/.icons/brands/discord.svg @@ -0,0 +1,9 @@ + + + + + + diff --git a/docs/_custom_theme/.icons/brands/mail.svg b/docs/_custom_theme/.icons/brands/mail.svg new file mode 100644 index 0000000..470f1b5 --- /dev/null +++ b/docs/_custom_theme/.icons/brands/mail.svg @@ -0,0 +1,8 @@ + + + + diff --git a/docs/_custom_theme/externalLinkIcon.html b/docs/_custom_theme/externalLinkIcon.html new file mode 100644 index 0000000..9e271ae --- /dev/null +++ b/docs/_custom_theme/externalLinkIcon.html @@ -0,0 +1,25 @@ +{% extends "base.html" %} + + + diff --git a/docs/_custom_theme/home.html b/docs/_custom_theme/home.html new file mode 100644 index 0000000..bbd5424 --- /dev/null +++ b/docs/_custom_theme/home.html @@ -0,0 +1,148 @@ +{% extends "main.html" %} +{% block tabs %} + +{{ super() }} + + + + + + + + + + + + + + + + +{% endblock %} +{% block content %} +
+ {{ page.content }} +
+{% endblock %} diff --git a/docs/_custom_theme/partials/toc-item.html b/docs/_custom_theme/partials/toc-item.html new file mode 100644 index 0000000..56a130b --- /dev/null +++ b/docs/_custom_theme/partials/toc-item.html @@ -0,0 +1,38 @@ +{# Copied and customized from: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/partials/toc-item.html #} +{# Table of contents item #} +
  • + + + + {# Typeset title #} + {% if toc_item.typeset %} + + {{ toc_item.typeset.title }} + + + {# Regular title #} + {% else %} + {{ toc_item.title }} + {% endif %} + + + + {# Table of contents list #} + {% if toc_item.children %} + + {% endif %} +
    • diff --git a/docs/_custom_theme/partials/toc.html b/docs/_custom_theme/partials/toc.html new file mode 100644 index 0000000..cbf27ed --- /dev/null +++ b/docs/_custom_theme/partials/toc.html @@ -0,0 +1,34 @@ +{# Copied and customized from: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/partials/toc.html #} +{% set title = lang.t("toc") %} +{% if config.mdx_configs.toc and config.mdx_configs.toc.title %} +{% set title = config.mdx_configs.toc.title %} +{% endif %} + + diff --git a/docs/_media/content/Home/waveDark.svg b/docs/_media/content/Home/waveDark.svg new file mode 100644 index 0000000..1b16e8a --- /dev/null +++ b/docs/_media/content/Home/waveDark.svg @@ -0,0 +1,15 @@ + + + Wave + + + + diff --git a/docs/_media/content/Home/waveWhite.svg b/docs/_media/content/Home/waveWhite.svg new file mode 100644 index 0000000..dacd512 --- /dev/null +++ b/docs/_media/content/Home/waveWhite.svg @@ -0,0 +1,15 @@ + + + Wave + + + + diff --git a/docs/_webCode/css/button.css b/docs/_webCode/css/button.css new file mode 100644 index 0000000..2bd6af2 --- /dev/null +++ b/docs/_webCode/css/button.css @@ -0,0 +1,5 @@ +.button-list { + width: 17em; + margin: 0.5em; + text-align: center; +} diff --git a/docs/_webCode/css/centered.css b/docs/_webCode/css/centered.css new file mode 100644 index 0000000..a410fab --- /dev/null +++ b/docs/_webCode/css/centered.css @@ -0,0 +1,7 @@ +.centered { + display: flex; + align-items: center; + justify-content: center } +.centered p { + margin-right: 0; + margin-left: 0; } diff --git a/docs/_webCode/css/coloredIcons.css b/docs/_webCode/css/coloredIcons.css new file mode 100644 index 0000000..b9fa8e6 --- /dev/null +++ b/docs/_webCode/css/coloredIcons.css @@ -0,0 +1,3 @@ +.task { + color: #00AB6C; +} diff --git a/docs/_webCode/css/contentAreaFullWidth.css b/docs/_webCode/css/contentAreaFullWidth.css new file mode 100644 index 0000000..509021c --- /dev/null +++ b/docs/_webCode/css/contentAreaFullWidth.css @@ -0,0 +1,3 @@ +.md-grid { + max-width: clamp(400px,80%,2048px); +} diff --git a/docs/_webCode/css/mermaidCentered.css b/docs/_webCode/css/mermaidCentered.css new file mode 100644 index 0000000..2b3a1d7 --- /dev/null +++ b/docs/_webCode/css/mermaidCentered.css @@ -0,0 +1,3 @@ +div.mermaid { + text-align: center; +} diff --git a/docs/_webCode/js/copyLinkToClipboard.js b/docs/_webCode/js/copyLinkToClipboard.js new file mode 100644 index 0000000..4ecafcb --- /dev/null +++ b/docs/_webCode/js/copyLinkToClipboard.js @@ -0,0 +1,17 @@ +//mkdocs-material provided observable that is called when the page is fully loaded. Respects both default and "instant loading" of pages. +document$.subscribe(function () { +//Adds an EventListener to all "chain link" elements next to headings. + let links = document.getElementsByClassName("headerlink"); + for (let i = 0; i < links.length; i++) { + links[i].addEventListener("click", onClick); + } + +//Copies the current URL into the users clipboard. +//This needs to be delayed by a bit since the browser needs to update the URL before it's copied. + function onClick() { + setTimeout(() => { + let url = window.location.href; + navigator.clipboard.writeText(url); + }, 10); + } +}); diff --git a/docs/_webCode/js/copyrightYearUpdater.js b/docs/_webCode/js/copyrightYearUpdater.js new file mode 100644 index 0000000..5584b16 --- /dev/null +++ b/docs/_webCode/js/copyrightYearUpdater.js @@ -0,0 +1,6 @@ +//mkdocs-material provided observable that is called when the page is fully loaded. Respects both default and "instant loading" of pages. +document$.subscribe(function () { + const copyrightElement = document.getElementById("bqCopyright"); + const currentYear = new Date().getFullYear().toString(); + copyrightElement.textContent = copyrightElement.textContent.replace("{CurrentYear}", currentYear); +}); diff --git a/docs/_webCode/js/mathjax.js b/docs/_webCode/js/mathjax.js new file mode 100644 index 0000000..06dbf38 --- /dev/null +++ b/docs/_webCode/js/mathjax.js @@ -0,0 +1,16 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.typesetPromise() +}) diff --git a/docs/mkdocs_parent.yml b/docs/mkdocs_parent.yml new file mode 100644 index 0000000..91ab9b1 --- /dev/null +++ b/docs/mkdocs_parent.yml @@ -0,0 +1,153 @@ +site_dir: target/docs +docs_dir: docs +edit_uri: edit/main/docs/ +copyright: > +

    © 2024-{CurrentYear}

    + Change cookie settings + +extra_css: + - '_webCode/css/button.css' + - '_webCode/css/centered.css' + - '_webCode/css/contentAreaFullWidth.css' + - '_webCode/css/coloredIcons.css' + - '_webCode/css/mermaidCentered.css' + +extra_javascript: + - '_webCode/js/copyLinkToClipboard.js' + - '_webCode/js/copyrightYearUpdater.js' + - '_webCode/js/mathjax.js' + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + +# More info on this theme: https://squidfunk.github.io/mkdocs-material +theme: + name: material + custom_dir: 'docs/_custom_theme/' + language: en + features: + - content.action.edit + - content.code.annotate + - content.code.copy + - content.tabs.link + - navigation.tabs + - navigation.tabs.sticky + - navigation.tracking + - navigation.sections + - navigation.top + - navigation.path + - navigation.instant + - navigation.instant.prefetch + - navigation.instant.progress + - search.share + - search.suggest + - content.tooltips + - toc.follow + + palette: + - scheme: slate + primary: indigo + accent: teal + toggle: + icon: material/lightbulb + name: Switch to light mode + - scheme: default + primary: blue + accent: teal + toggle: + icon: fontawesome/solid/moon + name: Switch to dark mode + font: + text: Roboto + code: Roboto Mono + logo: '_media/brand/Icon/Icon1K.png' + favicon: '_media/brand/Icon/Icon32.ico' + icon: + admonition: + example: fontawesome/regular/eye + + + +# See the following for docs on these extensions: https://squidfunk.github.io/mkdocs-material/extensions +markdown_extensions: + - admonition + - attr_list + - codehilite: + linenums: true + - footnotes + - markdown.extensions.md_in_html + - meta + - pymdownx.highlight + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic + - pymdownx.details + - pymdownx.keys + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + options: + custom_icons: + - '_custom_theme/.icons' + - pymdownx.inlinehilite + - pymdownx.magiclink + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + - abbr + - toc: + permalink: 🔗 + +plugins: + - search: { } + - snippets: + directory: "_snippets" + identifier: "snippet" + - exclude: + glob: + - _snippets/* + - _custom_theme/* + - _tutorials/* + - mkdocs_parent.yml + - setup-docs_dependencies.py + - group: + enabled: !ENV MKDOCS_MATERIAL_INSIDERS_ENABLED + plugins: + - typeset + - group: + enabled: !ENV MKDOCS_MATERIAL_INSIDERS_ENABLED_CI + plugins: + - optimize + +extra: + consent: + title: Cookie consent + cookies: + github: GitHub + actions: + - manage + - reject + - accept + description: > +

    We need your consent to make request to GitHub.com. We load statistics about our Git repository from there.

    + +validation: + nav: + omitted_files: warn + not_found: warn + absolute_links: warn + links: + not_found: warn + absolute_links: warn + unrecognized_links: warn diff --git a/docs/setup-docs-dependencies.py b/docs/setup-docs-dependencies.py new file mode 100644 index 0000000..d98ba9d --- /dev/null +++ b/docs/setup-docs-dependencies.py @@ -0,0 +1,29 @@ +import os +import subprocess + +common_dependencies = [ + 'mkdocs-snippets', + 'mike==2.1.3', + 'mkdocs-exclude==1.0.2', +] + + +def get_install_requires(): + mkdocs_token = os.environ.get('MKDOCS_MATERIAL_INSIDERS') + if mkdocs_token: + mkdocs_enabled = os.environ.get('MKDOCS_MATERIAL_INSIDERS_ENABLED') + if mkdocs_enabled == 'true': + return [ + f'git+https://{mkdocs_token}@github.com/squidfunk/mkdocs-material-insiders.git@9.5.33-insiders-4.53.12', + 'pillow', + 'cairosvg', + ] + common_dependencies + print("\033[93m" + + "Warning: 'MKDOCS_MATERIAL_INSIDERS' is set " + + "but 'MKDOCS_MATERIAL_INSIDERS_ENABLED' is not set to 'true', " + + "so if you serve mkdocs you will serve the normal version!" + + "\033[0m") + return ['mkdocs-material==9.5.33'] + common_dependencies + + +subprocess.run(['pip', 'install'] + get_install_requires())