From a3e011b7c15325912fb3815fe040f23a40c8f2f3 Mon Sep 17 00:00:00 2001 From: quasar Date: Tue, 13 Oct 2026 06:58:49 +0000 Subject: [PATCH 1/3] Resolve Issue #88: Implement GitHub Pages documentation site Material-styled MkDocs site containing the markdown documentation (README) and the Doxygen API documentation served under /api/. The "Deploy Documentation (GitHub Pages)" workflow installs Doxygen 1.9.8 and Graphviz via marketplace actions, generates the Doxygen HTML into docs/api/, builds the site with mkdocs-material and deploys it to the gh-pages branch. --- .github/workflows/deploy-docs.yml | 71 +++++++++++++++++++++++++++++++ .gitignore | 4 +- docs/index.md | 1 + mkdocs.yml | 65 ++++++++++++++++++++++++++++ 4 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/deploy-docs.yml create mode 120000 docs/index.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 00000000..a517d340 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,71 @@ +name: Deploy Documentation (GitHub Pages) + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: write + +jobs: + build-and-deploy: + name: Build the documentation site and deploy to GitHub Pages + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + # The full history is required to compute the + # 1.4.. project version. + fetch-depth: 0 + + - name: Install Doxygen + uses: ssciwr/doxygen-install@v2.0.3 + with: + # The version the documentation was generated and validated with. + version: 1.9.8 + + - name: Install Graphviz + uses: ts-graphviz/setup-graphviz@v2.0.2 + + - name: Generate the Doxygen configuration file + run: | + PROJECT_VERSION="1.4.$(git rev-list --count HEAD).$(git rev-parse --short HEAD)" + # Doxygen writes the HTML output into docs/api/ so that the + # MkDocs build serves it as the /api/ section of the site. + sed -e "s|@HEART_VERSION@|${PROJECT_VERSION}|" \ + -e "s|^OUTPUT_DIRECTORY = docs$|OUTPUT_DIRECTORY = docs/api|" \ + doxygen.conf.in > doxygen.conf + grep -E '^(PROJECT_NAME|PROJECT_NUMBER|OUTPUT_DIRECTORY)' doxygen.conf + + - name: Generate the Doxygen HTML documentation + run: doxygen doxygen.conf + + - name: Copy the images referenced by the README + run: | + # The README (site home page and Doxygen main page) links + # res/Banner_Web.png relative to its own location, so the image + # has to be available under /res/ (MkDocs home) and under + # /api/res/ (Doxygen main page). + mkdir -p docs/res docs/api/res + cp res/Banner_Web.png docs/res/ + cp res/Banner_Web.png docs/api/res/ + + - name: Install MkDocs and the Material theme + run: | + python -m pip install --upgrade pip + pip install mkdocs==1.6.1 mkdocs-material==9.7.7 + + - name: Build the documentation site + run: | + mkdocs build --strict + ls -la site site/api | head -40 + + - name: Deploy to GitHub Pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + branch: gh-pages + folder: site + clean: true diff --git a/.gitignore b/.gitignore index ef0421ca..669ad789 100644 --- a/.gitignore +++ b/.gitignore @@ -58,7 +58,9 @@ src/Heart_autogen/ src/cmake_install.cmake HeartTests/cmake_install.cmake cmake_install.cmake -docs/ +docs/api/ +docs/res/ +site/ src/heart_global.h doxygen.conf # git diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..d8820483 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,65 @@ +# Heart documentation site (GitHub Pages) +# +# Built with MkDocs + the Material theme. The Doxygen HTML output is +# generated into docs/api/ by the "Deploy Documentation (GitHub Pages)" +# workflow before `mkdocs build` runs, so the API section of the site +# is served from /api/. + +site_name: Heart +site_description: QuasarApp Heart - base backend for C++/Qt projects +site_url: https://quasarapp.github.io/Heart/ + +repo_name: QuasarApp/Heart +repo_url: https://github.com/QuasarApp/Heart +edit_uri: https://github.com/QuasarApp/Heart/edit/main/ + +docs_dir: docs +site_dir: site + +theme: + name: material + palette: + - scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-4 + name: Switch to dark mode + - scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to light mode + font: + text: Roboto + code: Roboto Mono + features: + - content.code.copy + - navigation.footer + - navigation.indexes + - navigation.sections + - navigation.top + - navigation.tracking + - search.highlight + - search.suggest + - toc + +markdown_extensions: + - admonition + - attr_list + - tables + - toc: + permalink: true + - pymdownx.details + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.tasklist: + custom_checkbox: true + +nav: + - Home: index.md + # api/index.html is the static Doxygen index generated into docs/api/ + # by the documentation workflow before the MkDocs build. + - API: api/index.html From ae04998afe643338f999ff1a1da5a4bc53c73ec1 Mon Sep 17 00:00:00 2001 From: quasar Date: Tue, 13 Oct 2026 07:21:43 +0000 Subject: [PATCH 2/3] Remove the docs/index.md symlink (EndrII review) The site home page is now generated at build time: the documentation workflow copies the root README.md to docs/index.md before 'mkdocs build'. The README stays the single source of truth and the generated copy is gitignored. The workflow also creates docs/ before running Doxygen, since removing the symlink leaves no tracked file in that directory. --- .github/workflows/deploy-docs.yml | 14 +++++++++++++- .gitignore | 1 + docs/index.md | 1 - mkdocs.yml | 10 +++++++--- 4 files changed, 21 insertions(+), 5 deletions(-) delete mode 120000 docs/index.md diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index a517d340..f2e1a704 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -41,7 +41,12 @@ jobs: grep -E '^(PROJECT_NAME|PROJECT_NUMBER|OUTPUT_DIRECTORY)' doxygen.conf - name: Generate the Doxygen HTML documentation - run: doxygen doxygen.conf + run: | + # The docs/ directory no longer exists in the repository + # (docs/index.md is generated at build time), so it has to be + # created before Doxygen writes its output into docs/api/. + mkdir -p docs + doxygen doxygen.conf - name: Copy the images referenced by the README run: | @@ -53,6 +58,13 @@ jobs: cp res/Banner_Web.png docs/res/ cp res/Banner_Web.png docs/api/res/ + - name: Copy the README as the site home page + run: | + # docs/index.md is generated from the root README.md at build + # time (it is gitignored), so the README stays the single + # source of truth for the site home page. + cp README.md docs/index.md + - name: Install MkDocs and the Material theme run: | python -m pip install --upgrade pip diff --git a/.gitignore b/.gitignore index 669ad789..d232977b 100644 --- a/.gitignore +++ b/.gitignore @@ -60,6 +60,7 @@ HeartTests/cmake_install.cmake cmake_install.cmake docs/api/ docs/res/ +docs/index.md site/ src/heart_global.h doxygen.conf diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index d8820483..55f95705 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,9 @@ # Heart documentation site (GitHub Pages) # -# Built with MkDocs + the Material theme. The Doxygen HTML output is -# generated into docs/api/ by the "Deploy Documentation (GitHub Pages)" -# workflow before `mkdocs build` runs, so the API section of the site +# Built with MkDocs + the Material theme. Before `mkdocs build` runs, +# the "Deploy Documentation (GitHub Pages)" workflow copies the root +# README.md to docs/index.md (the site home page) and generates the +# Doxygen HTML output into docs/api/, so the API section of the site # is served from /api/. site_name: Heart @@ -59,6 +60,9 @@ markdown_extensions: custom_checkbox: true nav: + # index.md is copied from the root README.md by the documentation + # workflow before the MkDocs build, so the README stays the single + # source of truth and the generated copy is not committed. - Home: index.md # api/index.html is the static Doxygen index generated into docs/api/ # by the documentation workflow before the MkDocs build. From 084f2ca9d4ee38ce8feb2d3fa6abf48af3029ef8 Mon Sep 17 00:00:00 2001 From: quasar Date: Tue, 13 Oct 2026 08:00:37 +0000 Subject: [PATCH 3/3] Address EndrII review on the docs site: Doxygen 1.18.0, Material styling, fixed README docs link --- .github/workflows/deploy-docs.yml | 5 +- README.md | 2 +- doxygen.conf.in | 143 +------------ res/doxygen-material.css | 332 ++++++++++++++++++++++++++++++ 4 files changed, 343 insertions(+), 139 deletions(-) create mode 100644 res/doxygen-material.css diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index f2e1a704..eb446d31 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -24,8 +24,9 @@ jobs: - name: Install Doxygen uses: ssciwr/doxygen-install@v2.0.3 with: - # The version the documentation was generated and validated with. - version: 1.9.8 + # The latest stable release the documentation was generated and + # validated with. + version: 1.18.0 - name: Install Graphviz uses: ts-graphviz/setup-graphviz@v2.0.2 diff --git a/README.md b/README.md index 61e6fe87..99cbaa97 100644 --- a/README.md +++ b/README.md @@ -153,4 +153,4 @@ public: } }; ``` -For more information, see our QuasarApp Heart [Code](https://quasarapp.ddns.net:3031/docs/QuasarApp/Heart/latest/) Documentation. +For more information, see our QuasarApp Heart [documentation](https://quasarapp.github.io/Heart/) and the [API reference](https://quasarapp.github.io/Heart/api/). diff --git a/doxygen.conf.in b/doxygen.conf.in index e3140f29..a18ba878 100644 --- a/doxygen.conf.in +++ b/doxygen.conf.in @@ -240,12 +240,6 @@ TAB_SIZE = 4 ALIASES = -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -703,7 +697,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = submodules/CMake/DoxyStyle/DoxygenLayout.xml +LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -1102,13 +1096,6 @@ CLANG_OPTIONS = ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1194,7 +1181,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = submodules/CMake/DoxyStyle/doxygenStyles.css +HTML_EXTRA_STYLESHEET = res/doxygen-material.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1215,7 +1202,7 @@ HTML_EXTRA_FILES = # Minimum value: 0, maximum value: 359, default value: 220. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE_HUE = 202 +HTML_COLORSTYLE_HUE = 231 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors # in the HTML output. For a value of 0 the output will use grayscales only. A @@ -1236,15 +1223,6 @@ HTML_COLORSTYLE_SAT = 212 HTML_COLORSTYLE_GAMMA = 59 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. @@ -1515,17 +1493,6 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES - # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # http://www.mathjax.org) which uses client side Javascript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX @@ -1605,8 +1572,11 @@ SEARCHENGINE = YES # "External Indexing and Searching" for details. # The default value is: NO. # This tag requires that the tag SEARCHENGINE is set to YES. +# +# The site is deployed to GitHub Pages, which is static hosting without a PHP +# backend, so the search has to be generated client side (search_data.js). -SERVER_BASED_SEARCH = YES +SERVER_BASED_SEARCH = NO # When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP # script for searching. Instead the search results are written to an XML file @@ -1804,16 +1774,6 @@ LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source -# code with syntax highlighting in the LaTeX output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_SOURCE_CODE = NO - # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See # http://en.wikipedia.org/wiki/BibTeX and \cite for more info. @@ -1822,14 +1782,6 @@ LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- @@ -1886,16 +1838,6 @@ RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = -# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code -# with syntax highlighting in the RTF output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_RTF is set to YES. - -RTF_SOURCE_CODE = NO - #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- @@ -1985,15 +1927,6 @@ GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the -# program listings (including syntax highlighting and cross-referencing -# information) to the DOCBOOK output. Note that enabling this will significantly -# increase the size of the DOCBOOK output. -# The default value is: NO. -# This tag requires that the tag GENERATE_DOCBOOK is set to YES. - -DOCBOOK_PROGRAMLISTING = NO - #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- @@ -2168,34 +2101,10 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -PERL_PATH = /usr/bin/perl - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. @@ -2228,23 +2137,6 @@ HAVE_DOT = YES DOT_NUM_THREADS = 0 -# When you want a differently looking font in the dot files that doxygen -# generates you can specify the font name using DOT_FONTNAME. You need to make -# sure dot is able to find the font, which can be done by putting it in a -# standard location or by setting the DOTFONTPATH environment variable or by -# setting DOT_FONTPATH to the directory containing the font. -# The default value is: Helvetica. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_FONTNAME = Helvetica - -# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of -# dot graphs. -# Minimum value: 4, maximum value: 24, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_FONTSIZE = 10 - # By default doxygen will tell dot to use the default font as specified with # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set # the path where dot can find it using this tag. @@ -2459,27 +2351,6 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not seem -# to support this out of the box. -# -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) support -# this, this feature is disabled by default. -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_MULTI_TARGETS = NO - # If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page # explaining the meaning of the various boxes and arrows in the dot generated # graphs. diff --git a/res/doxygen-material.css b/res/doxygen-material.css new file mode 100644 index 00000000..990c7f05 --- /dev/null +++ b/res/doxygen-material.css @@ -0,0 +1,332 @@ +/* + * doxygen-material.css + * + * Material Design restyling for the Doxygen HTML output. It is attached + * through the HTML_EXTRA_STYLESHEET tag and therefore loaded after the + * generated doxygen.css, so every rule in this file wins the cascade. + * + * Doxygen 1.18+ drives its look with CSS custom properties, which makes the + * restyle a pure palette/font re-mapping: the Material "indigo" scheme and + * the Roboto font stack of the MkDocs site (see mkdocs.yml) are applied to + * the light scheme, and the site's "slate" palette is applied to the dark + * scheme (Doxygen follows the system color scheme automatically). + * + * Palette reference (Material Design): + * indigo 50 #e8eaf6 indigo 100 #c5cae9 indigo 300 #9fa8da + * indigo 400 #7986cb indigo 500 #3f51b5 indigo 600 #3949ab + * indigo 700 #303f9f indigo A200 #536dfe + */ + +/* ------------------------------------------------------------------ */ +/* Light scheme */ +/* ------------------------------------------------------------------ */ +html { + /* page base */ + --page-background-color: #ffffff; + --page-foreground-color: rgba(0, 0, 0, 0.87); + --page-link-color: #3f51b5; + --page-visited-link-color: #303f9f; + --page-external-link-color: #536dfe; + + /* index */ + --index-odd-item-bg-color: #f4f5fb; + --index-even-item-bg-color: #ffffff; + --index-header-color: #303f9f; + --index-separator-color: #c5cae9; + + /* header (top app bar) */ + --header-background-color: #ffffff; + --header-separator-color: #e8eaf6; + --group-header-separator-color: #c5cae9; + --group-header-color: #3f51b5; + --footer-foreground-color: #3f51b5; + --citation-label-color: #3f51b5; + --glow-color: #9fa8da; + --title-background-color: #ffffff; + --title-separator-color: #e8eaf6; + + --blockquote-background-color: #f4f5fb; + --blockquote-border-color: #c5cae9; + + --scrollbar-thumb-color: #9fa8da; + --scrollbar-background-color: #f4f5fb; + + /* icons */ + --icon-background-color: #3f51b5; + --icon-foreground-color: #ffffff; + --icon-folder-open-fill-color: #c5cae9; + --icon-folder-fill-color: #e8eaf6; + --icon-folder-border-color: #3f51b5; + --icon-doc-fill-color: #e8eaf6; + --icon-doc-border-color: #3f51b5; + + /* brief member declaration list */ + --memdecl-background-color: #f4f5fb; + --memdecl-foreground-color: rgba(0, 0, 0, 0.7); + --memdecl-template-color: #3f51b5; + --memdecl-border-color: #e8eaf6; + + /* detailed member list */ + --memdef-border-color: #c5cae9; + --memdef-title-background-color: #e8eaf6; + --memdef-proto-background-color: #f4f5fb; + --memdef-proto-text-color: #303f9f; + --memdef-param-name-color: #6d4c41; + --memdef-template-color: #3f51b5; + + /* tables */ + --table-cell-border-color: #9fa8da; + --table-header-background-color: #3f51b5; + --table-header-foreground-color: #ffffff; + + /* labels */ + --label-background-color: #3f51b5; + --label-left-top-border-color: #303f9f; + --label-right-bottom-border-color: #9fa8da; + --label-foreground-color: #ffffff; + + /* navigation bar / tree / menu */ + --nav-background-color: #f4f5fb; + --nav-foreground-color: #3f51b5; + --nav-border-color: #e8eaf6; + --nav-breadcrumb-separator-color: #c5cae9; + --nav-breadcrumb-active-bg: #e8eaf6; + --nav-breadcrumb-color: #3f51b5; + --nav-splitbar-bg-color: #e8eaf6; + --nav-splitbar-handle-color: #9fa8da; + --nav-text-normal-color: #303f9f; + --nav-menu-button-color: #3f51b5; + --nav-menu-background-color: #ffffff; + --nav-menu-foreground-color: rgba(0, 0, 0, 0.7); + --nav-menu-active-bg: #e8eaf6; + --nav-menu-active-color: #3f51b5; + --nav-arrow-color: #c5cae9; + --nav-arrow-selected-color: #9fa8da; + + /* sync icon */ + --sync-icon-border-color: #e8eaf6; + --sync-icon-background-color: #f4f5fb; + --sync-icon-selected-background-color: #e8eaf6; + --sync-icon-color: #c5cae9; + --sync-icon-selected-color: #3f51b5; + + /* table of contents */ + --toc-background-color: #f4f5fb; + --toc-border-color: #e8eaf6; + --toc-header-color: #3f51b5; + + /* search field */ + --search-foreground-color: #909090; + --search-active-color: rgba(0, 0, 0, 0.87); + --search-box-border-color: #c5cae9; + --search-filter-highlight-bg-color: #3f51b5; + --search-results-foreground-color: #3f51b5; + + /* code fragments */ + --fragment-foreground-color: rgba(0, 0, 0, 0.87); + --fragment-background-color: #f8f9fd; + --fragment-border-color: #c5cae9; + --fragment-lineno-background-color: #eef0f7; + --fragment-lineno-foreground-color: rgba(0, 0, 0, 0.54); + --fragment-lineno-link-fg-color: #3f51b5; + --fragment-lineno-link-bg-color: #e8eaf6; + --fragment-lineno-link-hover-fg-color: #3f51b5; + --fragment-lineno-link-hover-bg-color: #c5cae9; + --fragment-copy-ok-color: #2e7d32; + + /* tooltips */ + --tooltip-foreground-color: rgba(0, 0, 0, 0.87); + --tooltip-background-color: rgba(255, 255, 255, 0.95); + --tooltip-arrow-background-color: #ffffff; + --tooltip-border-color: rgba(158, 168, 218, 0.7); + --tooltip-doc-color: #616161; + --tooltip-declaration-color: #2e7d32; + --tooltip-link-color: #3f51b5; + + /* fonts (same stack as the MkDocs site) */ + --font-family-normal: Roboto, system-ui, -apple-system, 'Segoe UI', Ubuntu, 'Noto Sans', sans-serif; + --font-family-monospace: 'Roboto Mono', 'JetBrains Mono', Consolas, Monaco, monospace; + --font-family-nav: Roboto, system-ui, sans-serif; + --font-family-title: Roboto, system-ui, sans-serif; + --font-family-toc: Roboto, system-ui, sans-serif; + --font-family-search: Roboto, system-ui, sans-serif; + --font-family-tooltip: Roboto, sans-serif; + +/* ------------------------------------------------------------------ */ +/* Dark scheme (the "slate" palette of the MkDocs site) */ +/* ------------------------------------------------------------------ */ +@media (prefers-color-scheme: dark) { + html:not(.dark-mode) { + /* page base */ + --page-background-color: #1e2129; + --page-foreground-color: rgba(255, 255, 255, 0.87); + --page-link-color: #9fa8da; + --page-visited-link-color: #c5cae9; + --page-external-link-color: #7986cb; + + /* index */ + --index-odd-item-bg-color: #262a35; + --index-even-item-bg-color: #1e2129; + --index-header-color: #c5cae9; + --index-separator-color: #3a4150; + + /* header (top app bar) */ + --header-background-color: #1a1d24; + --header-separator-color: #2e3442; + --group-header-separator-color: #3a4150; + --group-header-color: #9fa8da; + --footer-foreground-color: #9fa8da; + --citation-label-color: #9fa8da; + --glow-color: #536dfe; + --title-background-color: #1e2129; + --title-separator-color: #2e3442; + + --blockquote-background-color: #262a35; + --blockquote-border-color: #3a4150; + + --scrollbar-thumb-color: #4c5468; + --scrollbar-background-color: #1e2129; + + /* icons */ + --icon-background-color: #3f51b5; + --icon-foreground-color: #ffffff; + --icon-folder-open-fill-color: #4c5468; + --icon-folder-fill-color: #2e3442; + --icon-folder-border-color: #9fa8da; + --icon-doc-fill-color: #2e3442; + --icon-doc-border-color: #9fa8da; + + /* brief member declaration list */ + --memdecl-background-color: #262a35; + --memdecl-foreground-color: rgba(255, 255, 255, 0.7); + --memdecl-template-color: #9fa8da; + --memdecl-border-color: #2e3442; + + /* detailed member list */ + --memdef-border-color: #3a4150; + --memdef-title-background-color: #262a35; + --memdef-proto-background-color: #1a1d24; + --memdef-proto-text-color: #c5cae9; + --memdef-param-name-color: #ffab91; + --memdef-template-color: #9fa8da; + + /* tables */ + --table-cell-border-color: #4c5468; + --table-header-background-color: #303f9f; + --table-header-foreground-color: #ffffff; + + /* labels */ + --label-background-color: #3f51b5; + --label-left-top-border-color: #303f9f; + --label-right-bottom-border-color: #9fa8da; + --label-foreground-color: #ffffff; + + /* navigation bar / tree / menu */ + --nav-background-color: #1a1d24; + --nav-foreground-color: #9fa8da; + --nav-border-color: #2e3442; + --nav-breadcrumb-separator-color: #3a4150; + --nav-breadcrumb-active-bg: #262a35; + --nav-breadcrumb-color: #9fa8da; + --nav-splitbar-bg-color: #262a35; + --nav-splitbar-handle-color: #4c5468; + --nav-text-normal-color: #c5cae9; + --nav-menu-button-color: #9fa8da; + --nav-menu-background-color: #1e2129; + --nav-menu-foreground-color: rgba(255, 255, 255, 0.7); + --nav-menu-active-bg: #262a35; + --nav-menu-active-color: #9fa8da; + --nav-arrow-color: #3a4150; + --nav-arrow-selected-color: #9fa8da; + + /* sync icon */ + --sync-icon-border-color: #2e3442; + --sync-icon-background-color: #1a1d24; + --sync-icon-selected-background-color: #262a35; + --sync-icon-color: #3a4150; + --sync-icon-selected-color: #9fa8da; + + /* table of contents */ + --toc-background-color: #1a1d24; + --toc-border-color: #2e3442; + --toc-header-color: #9fa8da; + + /* search field */ + --search-foreground-color: #9aa3b5; + --search-active-color: rgba(255, 255, 255, 0.87); + --search-box-border-color: #3a4150; + --search-filter-background-color: rgba(30, 33, 41, 0.85); + --search-filter-foreground-color: rgba(255, 255, 255, 0.87); + --search-filter-border-color: rgba(76, 84, 104, 0.6); + --search-filter-highlight-bg-color: #3f51b5; + --search-results-background-color: rgba(30, 33, 41, 0.95); + --search-results-foreground-color: #9fa8da; + --search-results-border-color: rgba(76, 84, 104, 0.6); + --search-close-icon-bg-color: #5c657a; + + /* code fragments */ + --fragment-foreground-color: rgba(255, 255, 255, 0.87); + --fragment-background-color: #1a1d24; + --fragment-border-color: #3a4150; + --fragment-lineno-background-color: #262a35; + --fragment-lineno-foreground-color: rgba(255, 255, 255, 0.54); + --fragment-lineno-link-fg-color: #9fa8da; + --fragment-lineno-link-bg-color: #2e3442; + --fragment-lineno-link-hover-fg-color: #9fa8da; + --fragment-lineno-link-hover-bg-color: #3a4150; + --fragment-copy-ok-color: #4caf50; + + /* tooltips */ + --tooltip-foreground-color: rgba(255, 255, 255, 0.87); + --tooltip-background-color: rgba(26, 29, 36, 0.95); + --tooltip-arrow-background-color: #1a1d24; + --tooltip-border-color: rgba(76, 84, 104, 0.7); + --tooltip-doc-color: #b0bec5; + --tooltip-declaration-color: #66bb6a; + --tooltip-link-color: #9fa8da; + --tooltip-shadow: none; + + /* fonts (same stack as the MkDocs site) */ + --font-family-normal: Roboto, system-ui, -apple-system, 'Segoe UI', Ubuntu, 'Noto Sans', sans-serif; + --font-family-monospace: 'Roboto Mono', 'JetBrains Mono', Consolas, Monaco, monospace; + --font-family-nav: Roboto, system-ui, sans-serif; + --font-family-title: Roboto, system-ui, sans-serif; + --font-family-toc: Roboto, system-ui, sans-serif; + --font-family-search: Roboto, system-ui, sans-serif; + --font-family-tooltip: Roboto, sans-serif; + } +} + +/* ------------------------------------------------------------------ */ +/* Small Material structural tweaks (both schemes) */ +/* ------------------------------------------------------------------ */ + +/* elevation for the top app bar */ +#top { + box-shadow: 0 1px 4px rgba(0, 0, 0, 0.12); +} + +/* medium-weight titles, like Material headlines */ +#projectname { + font-weight: 500; +} + +#projectnumber { + color: var(--memdecl-template-color); +} + +h1.groupheader, +h2.groupheader, +h3.groupheader { + font-weight: 500; +} + +/* rounded search field and breadcrumb chip */ +#MSearchField { + border-radius: 4px; +} + +#nav-path ul { + border-radius: 4px; +} +} \ No newline at end of file