From 2b372c14e424b2073323a66352f09e5a8c70a325 Mon Sep 17 00:00:00 2001 From: tooomm Date: Sat, 24 Jan 2026 11:22:43 +0100 Subject: [PATCH] Docs: Use `doxygen-awesome-css` theme (#6512) * add doxygen-theme-css submodule * enable theme and disable not needed code references * hide nav sync button * css and cleanup * Move comments to dedicated README to not fail config check --- .gitmodules | 3 ++ Doxyfile | 12 ++++--- cockatrice/resources/help/deck_search.md | 2 +- cockatrice/resources/help/search.md | 2 +- doc/doxygen/DoxygenLayout.xml | 13 ++++---- doc/doxygen/README.md | 14 ++++++++ doc/doxygen/css/cockatrice_docs_style.css | 33 +++++++++++++++++++ ...oxygen_style.css => doxygen_style_old.css} | 0 doc/doxygen/css/hide_nav_sync.css | 10 ++++++ doc/doxygen/extra-pages/index.md | 12 +++---- .../extra-pages/user_documentation/index.md | 8 ++--- doc/doxygen/theme | 1 + 12 files changed, 86 insertions(+), 24 deletions(-) create mode 100644 doc/doxygen/README.md create mode 100644 doc/doxygen/css/cockatrice_docs_style.css rename doc/doxygen/css/{doxygen_style.css => doxygen_style_old.css} (100%) create mode 100644 doc/doxygen/css/hide_nav_sync.css create mode 160000 doc/doxygen/theme diff --git a/.gitmodules b/.gitmodules index a0a57f3d7..732fec7ca 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,6 @@ [submodule "vcpkg"] path = vcpkg url = https://github.com/microsoft/vcpkg.git +[submodule "doxygen-awesome-css"] + path = doc/doxygen/theme + url = https://github.com/jothepro/doxygen-awesome-css.git diff --git a/Doxyfile b/Doxyfile index ecacc6b8f..0f2642fd8 100644 --- a/Doxyfile +++ b/Doxyfile @@ -54,7 +54,7 @@ PROJECT_NUMBER = $(COCKATRICE_REF) # for a project that appears at the top of each page and should give viewers a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "A cross-platform virtual tabletop for multiplayer card games" +PROJECT_BRIEF = "A virtual tabletop for multiplayer card games" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -1068,6 +1068,8 @@ RECURSIVE = YES EXCLUDE = build/ \ cmake/ \ + doc/doxygen/theme/docs/ \ + doc/doxygen/theme/include/ \ vcpkg/ \ webclient/ @@ -1430,7 +1432,9 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = doc/doxygen/css/doxygen_style.css +HTML_EXTRA_STYLESHEET = doc/doxygen/theme/doxygen-awesome.css \ + doc/doxygen/css/hide_nav_sync.css \ + doc/doxygen/css/cockatrice_docs_style.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 @@ -1453,7 +1457,7 @@ HTML_EXTRA_FILES = doc/doxygen/js/graph_toggle.js # The default value is: AUTO_LIGHT. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE = AUTO_DARK +HTML_COLORSTYLE = LIGHT # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to @@ -1764,7 +1768,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -DISABLE_INDEX = YES +DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag diff --git a/cockatrice/resources/help/deck_search.md b/cockatrice/resources/help/deck_search.md index 2ddad9e66..3263daf04 100644 --- a/cockatrice/resources/help/deck_search.md +++ b/cockatrice/resources/help/deck_search.md @@ -49,4 +49,4 @@ searches are case insensitive.
Grouping:
red -([[]]:100 or aggro) (Any deck that has red in its filename but is not 100 cards or has aggro in its filename)
- + \ No newline at end of file diff --git a/cockatrice/resources/help/search.md b/cockatrice/resources/help/search.md index 6f25e4013..63e6e74c3 100644 --- a/cockatrice/resources/help/search.md +++ b/cockatrice/resources/help/search.md @@ -67,4 +67,4 @@ In this list of examples below, each entry has an explanation and can be clicked
[o:/counter target .* spell/](#o:/counter target .* spell/) (Any card text with "counter target *something* spell")
[o:/for each .* and\/or .*/](#o:/for each .* and\/or .*/) (/'s can be escaped with a \)
- + \ No newline at end of file diff --git a/doc/doxygen/DoxygenLayout.xml b/doc/doxygen/DoxygenLayout.xml index d6847755b..551391db3 100644 --- a/doc/doxygen/DoxygenLayout.xml +++ b/doc/doxygen/DoxygenLayout.xml @@ -7,7 +7,7 @@ - + @@ -15,9 +15,8 @@ - - - + + @@ -28,11 +27,11 @@ - + - + @@ -41,7 +40,7 @@ - + diff --git a/doc/doxygen/README.md b/doc/doxygen/README.md new file mode 100644 index 000000000..988147159 --- /dev/null +++ b/doc/doxygen/README.md @@ -0,0 +1,14 @@ +## Doxygen Documentation Theme + +Required changes to the `Doxyfile` config from the [theme docs](https://jothepro.github.io/doxygen-awesome-css/index.html#autotoc_md16) to make [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css) work: +``` +HTML_EXTRA_STYLESHEET = doxygen-awesome.css # Main CSS file of the theme +GENERATE_TREEVIEW = YES # Optional, also works without +HTML_COLORSTYLE = LIGHT # Required with doxygen-awesome-css theme, Auto Dark Mode will still work +DISABLE_INDEX = NO # YES is bugged in the theme, see jothepro/doxygen-awesome-css/issues/201 +FULL_SIDEBAR = NO # Required for doxygen-awesome-css theme +``` + +
+ +Cockatrice dedicated color adjustments are configured in the [cockatrice_docs_style.css](https://github.com/Cockatrice/Cockatrice/blob/master/doc/doxygen/css/cockatrice_docs_style.css) file that uses & overrides the theme definitions. diff --git a/doc/doxygen/css/cockatrice_docs_style.css b/doc/doxygen/css/cockatrice_docs_style.css new file mode 100644 index 000000000..e0177bdbb --- /dev/null +++ b/doc/doxygen/css/cockatrice_docs_style.css @@ -0,0 +1,33 @@ +/* + +See "Awesome Doxygen CSS" theme docs: +https://jothepro.github.io/doxygen-awesome-css/md_docs_2customization.html#autotoc_md36 + +Adjustments here are based on the css file of the theme and variables defined there. + +*/ + + +/* Light Mode overrides */ +html { + --primary-color: #33a946; + --primary-dark-color: #33a946; + --primary-light-color: #33a946; +} + +/* Dark Mode overrides */ +@media (prefers-color-scheme: dark) { + html:not(.light-mode) { + --primary-color: #33a946; + --primary-dark-color: #33a946; + --primary-light-color: #33a946; + } +} + +/* Dark Mode overrides, defined twice to support both the dark-mode without and with doxygen-awesome-darkmode-toggle.js */ +html.dark-mode { + color-scheme: dark; + --primary-color: #33a946; + --primary-dark-color: #33a946; + --primary-light-color: #33a946; +} diff --git a/doc/doxygen/css/doxygen_style.css b/doc/doxygen/css/doxygen_style_old.css similarity index 100% rename from doc/doxygen/css/doxygen_style.css rename to doc/doxygen/css/doxygen_style_old.css diff --git a/doc/doxygen/css/hide_nav_sync.css b/doc/doxygen/css/hide_nav_sync.css new file mode 100644 index 000000000..ad06ce6ed --- /dev/null +++ b/doc/doxygen/css/hide_nav_sync.css @@ -0,0 +1,10 @@ +/* hide navigation sync control and icons */ +#nav-sync, +#nav-sync * { + display: none !important; +} + +div.nav-sync-icon, +div.nav-sync-icon * { + display: none !important; +} \ No newline at end of file diff --git a/doc/doxygen/extra-pages/index.md b/doc/doxygen/extra-pages/index.md index b5c2b61e5..b3363d3f4 100644 --- a/doc/doxygen/extra-pages/index.md +++ b/doc/doxygen/extra-pages/index.md @@ -1,10 +1,8 @@ -@mainpage Cockatrice Documentation +@mainpage Documentation -# Welcome +Welcome to the Cockatrice code documentation. -This is the **main landing page** of the Cockatrice documentation. +- @subpage user_reference +- @subpage developer_reference -- Go to the @subpage user_reference page -- Review the @subpage developer_reference - -Or check out the Cockatrice Webpage. +Please also check the Cockatrice Webpage or our Code Repository for general information. diff --git a/doc/doxygen/extra-pages/user_documentation/index.md b/doc/doxygen/extra-pages/user_documentation/index.md index 29e76eff6..3f10a0ac6 100644 --- a/doc/doxygen/extra-pages/user_documentation/index.md +++ b/doc/doxygen/extra-pages/user_documentation/index.md @@ -1,17 +1,17 @@ @page user_reference User Reference -# Deck Management +## Deck Management - @subpage creating_decks - @subpage importing_decks - @subpage editing_decks - @subpage exporting_decks -# Release Channels +## Release Channels - @subpage beta_release -# Syntax Help +## Syntax Help - @subpage search_syntax_help -- @subpage deck_search_syntax_help \ No newline at end of file +- @subpage deck_search_syntax_help diff --git a/doc/doxygen/theme b/doc/doxygen/theme new file mode 160000 index 000000000..1f3620084 --- /dev/null +++ b/doc/doxygen/theme @@ -0,0 +1 @@ +Subproject commit 1f3620084ff75734ed192101acf40e9dff01d848