+
+ +@warning +- This theme is not compatible with the `FULL_SIDEBAR = YES` option provided by Doxygen! +- `HTML_COLORSTYLE` must be set to `LIGHT` since Doxygen 1.9.5! + +### Further installation instructions + +- [Installing extensions](docs/extensions.md) +- [Customizing the theme (colors, spacing, border-radius, ...)](docs/customization.md) - [Tips and Tricks for further configuration](docs/tricks.md) ## Browser support Tested with -- Chrome 98, Chrome 98 for Android, Chrome 87 for iOS -- Safari 15, Safari for iOS 15 -- Firefox 97, Firefox Daylight 97 for Android, Firefox Daylight 96 for iOS +- Chrome 119, Chrome 119 for Android, Chrome 119 for iOS +- Safari 17, Safari for iOS 16 +- Firefox 118, Firefox 120 for Android, Firefox 119 for iOS +- Edge 119 +- Opera 108 + + +The theme does not strive to be backward compatible with (significantly) older browser versions. + ## Credits -- This theme is inspired by the [vuepress](https://vuepress.vuejs.org/) static site generator default theme. -- Thank you for all the feedback on github! +Thanks for all the bug reports and inspiring feedback on GitHub! - +Special thanks to all the contributors: +
+ +
+
-Read Next: [Extensions](docs/extensions.md)
-
\ No newline at end of file
+
+
diff --git a/Docs/doxygen-awesome-css/docs/customization.md b/Docs/doxygen-awesome-css/docs/customization.md
index 0e89511b..7c26d338 100644
--- a/Docs/doxygen-awesome-css/docs/customization.md
+++ b/Docs/doxygen-awesome-css/docs/customization.md
@@ -7,10 +7,12 @@
This theme is highly customizable because a lot of things are parameterized with CSS variables.
-Just to give you an idea on how flexible the styling is, click this button:
+Just to give you an idea of how flexible the styling is, click this button:
+
+ ### Setup It is recommended to add your own `custom.css` and overwrite the variables there: @@ -26,15 +28,18 @@ html { } ``` -For dark-mode overrides you have to choose where to put them, depending on wether the dark-mode toggle extension is installed or not: +For dark-mode overrides, you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not: + +
primary theme colors. This will affect the entire websites color scheme: links, arrows, labels, ... ||| -| `--primary-color` | #1779c4 | #1982d2 | -| `--primary-dark-color` | #335c80 | #5ca8e2 | -| `--primary-light-color` | #70b1e9 | #4779ac | -| **Page Colors**:
background and foreground (text-color) of the documentation. ||| -| `--page-background-color` | white | #1C1D1F | -| `--page-foreground-color` | #2f4153 | #d2dbde | -| `--page-secondary-foreground-color`| #637485| #859399 | -| **Spacing:**
default spacings. Most ui components reference these values for spacing, to provide uniform spacing on the page. ||| -| `--spacing-small` | `5px` | | -| `--spacing-medium` | `10px` | | -| `--spacing-large` | `16px` | | -| **Border Radius**:
border radius for all rounded ui components. Will affect many components, like dropdowns, memitems, codeblocks, ... ||| -| `--border-radius-small` | `4px` | | -| `--border-radius-medium` | `6px` | | -| `--border-radius-large` | `8px` | | -| **Content Width**:
The content is centered and constrained in its width. To make the content fill the whole page, set the following variable to `auto`. ||| -| `--content-maxwidth` | `1000px` | | -| **Code Fragment Colors**:
Color-Scheme of multiline codeblocks ||| -| `--fragment-background` | #F8F9FA | #282c34 | -| `--fragment-foreground` | #37474F | #dbe4eb | -| **Arrow Opacity**:
By default the arrows in the sidebar are only visible on hover. You can override this behaviour so they are visible all the time. ||| -| `--side-nav-arrow-opacity` | `0` | | -| `--side-nav-arrow-hover-opacity` | `0.9` | | -| ...and many more ||| +| Parameter | Default (Light) | Default (Dark) | +| :---------------------------------- | :---------------------------------------------------------- | :---------------------------------------------------------- | +| **Color Scheme**:
primary theme colors. This will affect the entire websites color scheme: links, arrows, labels, ... ||| +| `--primary-color` |
background and foreground (text-color) of the documentation. ||| +| `--page-background-color` |
default spacings. Most ui components reference these values for spacing, to provide uniform spacing on the page. ||| +| `--spacing-small` | `5px` | | +| `--spacing-medium` | `10px` | | +| `--spacing-large` | `16px` | | +| **Border Radius**:
border radius for all rounded ui components. Will affect many components, like dropdowns, memitems, codeblocks, ... ||| +| `--border-radius-small` | `4px` | | +| `--border-radius-medium` | `6px` | | +| `--border-radius-large` | `8px` | | +| **Content Width**:
The content is centered and constrained in its width. To make the content fill the whole page, set the following variable to `auto`. ||| +| `--content-maxwidth` | `1000px` | | +| **Code Fragment Colors**:
Color-Scheme of multiline codeblocks ||| +| `--fragment-background` |
By default the arrows in the sidebar are only visible on hover. You can override this behavior so they are visible all the time. ||| +| `--side-nav-arrow-opacity` | `0` | | +| `--side-nav-arrow-hover-opacity` | `0.9` | | +| ...and many more ||| If you miss a configuration option or find a bug, please consider [opening an issue](https://github.com/jothepro/doxygen-awesome-css/issues)! @@ -85,11 +92,11 @@ If you miss a configuration option or find a bug, please consider [opening an is The theme overrides most colors with the `--primary-color-*` variables. -But there is a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with +But there are a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with the rest, it is recommended to adjust the [doxygen color settings](https://www.doxygen.nl/manual/customize.html#minor_tweaks_colors) -to something that matches the chosen color-scheme. +to something that matches the chosen color scheme. -For the default color-scheme, these values work out quite well: +For the default color scheme, these values work out quite well: ``` # Doxyfile @@ -100,11 +107,15 @@ HTML_COLORSTYLE_GAMMA = 113 ## Share your customizations -If you customized the theme with custom colors, spacings, font-sizes, etc. and you want to share your creation with others, you can to this [here](https://github.com/jothepro/doxygen-awesome-css/discussions/13). +If you have customized the theme with custom colors, spacings, font-sizes, etc. and you want to share your creation with others, you can do this [here](https://github.com/jothepro/doxygen-awesome-css/discussions/13). I am always curious to learn about how you made the theme look even better! - \ No newline at end of file + \ No newline at end of file diff --git a/Docs/doxygen-awesome-css/docs/extensions.md b/Docs/doxygen-awesome-css/docs/extensions.md index 8eb82d93..ea1ce00d 100644 --- a/Docs/doxygen-awesome-css/docs/extensions.md +++ b/Docs/doxygen-awesome-css/docs/extensions.md @@ -4,7 +4,7 @@ On top of the base theme provided by `doxygen-awesome.css`, this repository comes with Javascript extensions that require additional setup steps to get them running. -The extensions require customizations in the header HTML-template. +The extensions require customizations in the header HTML template. This is how you can create the default template with Doxygen: 1. Create default header template: @@ -19,11 +19,14 @@ This is how you can create the default template with Doxygen: [More details on header customization](https://www.doxygen.nl/manual/customize.html#minor_tweaks_header_css) -## Dark Mode Toggle +## Dark Mode Toggle {#extension-dark-mode-toggle} -Adds a button next to the search bar to enable and disable the dark theme variant manually. +Adds a button next to the search bar to enable and disable the dark theme variant manually: -
+
+
-**Doxygen Awesome** is a custom **CSS theme for Doxygen HTML-documentation** with lots of customization parameters.
+**Doxygen Awesome** is a custom CSS theme for Doxygen HTML documentation with lots of customization parameters.
## Motivation
-I really like how the Doxygen HTML-documentation is structured! But IMHO it looks a bit outdated.
+I really like how the Doxygen HTML documentation is structured! But IMHO it looks a bit outdated.
-This theme is an attemt to update the visuals of Doxygen without changing it's overall layout too much.
+This theme is an attempt to update the visuals of Doxygen without changing its overall layout too much.
## Features
- 🌈 Clean, modern design
-- 🚀 Heavily customizable by adjusting CSS-variables
-- 🧩 No changes to the HTML structure of Doxygen required
+- 🚀 Heavily customizable by adjusting CSS variables
+- 🧩 No changes to the HTML structure of Doxygen are required
- 📱 Improved mobile usability
- 🌘 Dark mode support!
-- 🥇 Works best with **doxygen 1.9.1** - **1.9.3**
+- 🥇 Works best with **doxygen 1.9.1** - **1.9.4** and **1.9.6** - **1.10.0**
## Examples
-- Sidebar-Only theme: [Documentation of this repository](https://jothepro.github.io/doxygen-awesome-css/)
-- Base theme: [libsl3](https://a4z.github.io/libsl3/)
-
+Some websites using this theme:
+
+- [Documentation of this repository](https://jothepro.github.io/doxygen-awesome-css/)
+- [wxWidgets](https://docs.wxwidgets.org/3.2/)
+- [OpenCV 5.x](https://docs.opencv.org/5.x/)
+- [Zephyr](https://docs.zephyrproject.org/latest/doxygen/html/index.html)
+- [FELTOR](https://mwiesenberger.github.io/feltor/dg/html/modules.html)
+- [Spatial Audio Framework (SAF)](https://leomccormack.github.io/Spatial_Audio_Framework/index.html)
+- [Randolf Richardson's C++ classes](https://www.randolf.ca/c++/docs/)
+- [libCloudSync](https://jothepro.github.io/libCloudSync/)
+- [libsl3](https://a4z.github.io/libsl3/)
+
## Installation
-Copy the file `doxygen-awesome.css` from this repository into your project or add this repository as submodule and check out the latest release:
+To use the theme when generating your documentation, bring the required CSS and JS files from this repository into your project.
+
+This can be done in several ways:
+
+- manually copying the files
+- adding the project as a Git submodule
+- adding the project as a npm/xpm dependency
+- installing the theme system-wide
+
+All theme files are located in the root of this repository and start with the prefix `doxygen-awesome-`. You may not need all of them. Follow the install instructions to figure out what files are required for your setup.
-```bash
+### Git submodule
+For projects that use git, add the repository as a submodule and check out the desired release:
+
+```sh
git submodule add https://github.com/jothepro/doxygen-awesome-css.git
cd doxygen-awesome-css
-git checkout v2.0.2
+git checkout v2.3.3
```
-Choose one of the theme variants and configure Doxygen accordingly:
-
-
+### npm/xpm dependency
-
+In the npm ecosystem, this project can be added as a development dependency
+to your project:
-
+```sh
+cd your-project
+npm install https://github.com/jothepro/doxygen-awesome-css#v2.3.3 --save-dev
-1. **Base theme**:
-```
-# Doxyfile
-GENERATE_TREEVIEW = YES # optional. Also works without treeview
-HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
+ls -l node_module/@jothepro/doxygen-awesome-css
```
-2. **Sidebar-only theme**:
-```
-# Doxyfile
-GENERATE_TREEVIEW = YES # required!
-HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \
- doxygen-awesome-css/doxygen-awesome-sidebar-only.css
-```
+Similarly, in the [xPack](https://xpack.github.io) ecosystem, this project can be added
+as a development dependency to an [`xpm`](https://xpack.github.io/xpm/)
+managed project.
+
+### System-wide
+
+You can even install the theme system-wide by running `make install`.
+The files will be installed to `/usr/local/share/` by default,
+but you can customize the install location with `make PREFIX=/my/custom/path install`.
+
+### Choosing a layout
+
+There are two layout options. Choose one of them and configure Doxygen accordingly:
+
+
+
+- Base Theme
+
+
+ 
+
+ Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled.
+
+ Required files: `doxygen-awesome.css`
-Further installation instructions:
+ Required `Doxyfile` configuration:
+ ```
+ GENERATE_TREEVIEW = YES # optional. Also works without treeview
+ DISABLE_INDEX = NO
+ FULL_SIDEBAR = NO
+ HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
+ HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
+ ```
-- [How to install extensions](docs/extensions.md)
-- [How to customize the theme (colors, spacing, border-radius, ...)](docs/customization.md)
+- Sidebar-Only Theme
+ 
+
+ Hides the top titlebar to give more space to the content. The treeview must be enabled in order for this theme to work.
+
+ Required files: `doxygen-awesome.css`, `doxygen-awesome-sidebar-only.css`
+
+ Required `Doxyfile` configuration:
+ ```
+
+ GENERATE_TREEVIEW = YES # required!
+ DISABLE_INDEX = NO
+ FULL_SIDEBAR = NO
+ HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \
+ doxygen-awesome-css/doxygen-awesome-sidebar-only.css
+ HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
+ ```
+
++ +@warning +- This theme is not compatible with the `FULL_SIDEBAR = YES` option provided by Doxygen! +- `HTML_COLORSTYLE` must be set to `LIGHT` since Doxygen 1.9.5! + +### Further installation instructions + +- [Installing extensions](docs/extensions.md) +- [Customizing the theme (colors, spacing, border-radius, ...)](docs/customization.md) - [Tips and Tricks for further configuration](docs/tricks.md) ## Browser support Tested with -- Chrome 98, Chrome 98 for Android, Chrome 87 for iOS -- Safari 15, Safari for iOS 15 -- Firefox 97, Firefox Daylight 97 for Android, Firefox Daylight 96 for iOS +- Chrome 119, Chrome 119 for Android, Chrome 119 for iOS +- Safari 17, Safari for iOS 16 +- Firefox 118, Firefox 120 for Android, Firefox 119 for iOS +- Edge 119 +- Opera 108 + + +The theme does not strive to be backward compatible with (significantly) older browser versions. + ## Credits -- This theme is inspired by the [vuepress](https://vuepress.vuejs.org/) static site generator default theme. -- Thank you for all the feedback on github! +Thanks for all the bug reports and inspiring feedback on GitHub! - +Special thanks to all the contributors: +
+ +
+ ### Setup It is recommended to add your own `custom.css` and overwrite the variables there: @@ -26,15 +28,18 @@ html { } ``` -For dark-mode overrides you have to choose where to put them, depending on wether the dark-mode toggle extension is installed or not: +For dark-mode overrides, you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not: + +
-- dark-mode toggle is installed:
+- dark-mode toggle is installed
```css
html.dark-mode {
/* define dark-mode variable overrides here if you DO use doxygen-awesome-darkmode-toggle.js */
}
```
-- dark-mode toggle is **NOT** installed. The dark-mode is enabled automatically depending on the system preference:
+- dark-mode toggle is **NOT** installed
+ The dark-mode is enabled automatically depending on the system preference:
```css
@media (prefers-color-scheme: dark) {
html:not(.light-mode) {
@@ -43,6 +48,8 @@ For dark-mode overrides you have to choose where to put them, depending on wethe
}
```
+
+
### Available variables
The following list gives an overview of the variables defined in [`doxygen-awesome.css`](https://github.com/jothepro/doxygen-awesome-css/blob/main/doxygen-awesome.css).
@@ -50,33 +57,33 @@ The following list gives an overview of the variables defined in [`doxygen-aweso
The list is not complete. To explore all available variables, have a look at the CSS starting from [here](https://github.com/jothepro/doxygen-awesome-css/blob/main/doxygen-awesome.css#L30).
All variables are defined at the beginning of the stylesheet.
-| Parameter | Default (Light) | Default (Dark) |
-| :-------------------------------- | :---------------------------------------------------------- | ----------------------------------------------------------- |
-| **Color Scheme**:primary theme colors. This will affect the entire websites color scheme: links, arrows, labels, ... ||| -| `--primary-color` | #1779c4 | #1982d2 | -| `--primary-dark-color` | #335c80 | #5ca8e2 | -| `--primary-light-color` | #70b1e9 | #4779ac | -| **Page Colors**:
background and foreground (text-color) of the documentation. ||| -| `--page-background-color` | white | #1C1D1F | -| `--page-foreground-color` | #2f4153 | #d2dbde | -| `--page-secondary-foreground-color`| #637485| #859399 | -| **Spacing:**
default spacings. Most ui components reference these values for spacing, to provide uniform spacing on the page. ||| -| `--spacing-small` | `5px` | | -| `--spacing-medium` | `10px` | | -| `--spacing-large` | `16px` | | -| **Border Radius**:
border radius for all rounded ui components. Will affect many components, like dropdowns, memitems, codeblocks, ... ||| -| `--border-radius-small` | `4px` | | -| `--border-radius-medium` | `6px` | | -| `--border-radius-large` | `8px` | | -| **Content Width**:
The content is centered and constrained in its width. To make the content fill the whole page, set the following variable to `auto`. ||| -| `--content-maxwidth` | `1000px` | | -| **Code Fragment Colors**:
Color-Scheme of multiline codeblocks ||| -| `--fragment-background` | #F8F9FA | #282c34 | -| `--fragment-foreground` | #37474F | #dbe4eb | -| **Arrow Opacity**:
By default the arrows in the sidebar are only visible on hover. You can override this behaviour so they are visible all the time. ||| -| `--side-nav-arrow-opacity` | `0` | | -| `--side-nav-arrow-hover-opacity` | `0.9` | | -| ...and many more ||| +| Parameter | Default (Light) | Default (Dark) | +| :---------------------------------- | :---------------------------------------------------------- | :---------------------------------------------------------- | +| **Color Scheme**:
primary theme colors. This will affect the entire websites color scheme: links, arrows, labels, ... ||| +| `--primary-color` |
#1779c4 | #1982d2 |
+| `--primary-dark-color` | #335c80 | #5ca8e2 |
+| `--primary-light-color` | #70b1e9 | #4779ac |
+| **Page Colors**:background and foreground (text-color) of the documentation. ||| +| `--page-background-color` |
#ffffff | #1C1D1F |
+| `--page-foreground-color` | #2f4153 | #d2dbde |
+| `--page-secondary-foreground-color` | #6f7e8e | #859399 |
+| **Spacing:**default spacings. Most ui components reference these values for spacing, to provide uniform spacing on the page. ||| +| `--spacing-small` | `5px` | | +| `--spacing-medium` | `10px` | | +| `--spacing-large` | `16px` | | +| **Border Radius**:
border radius for all rounded ui components. Will affect many components, like dropdowns, memitems, codeblocks, ... ||| +| `--border-radius-small` | `4px` | | +| `--border-radius-medium` | `6px` | | +| `--border-radius-large` | `8px` | | +| **Content Width**:
The content is centered and constrained in its width. To make the content fill the whole page, set the following variable to `auto`. ||| +| `--content-maxwidth` | `1000px` | | +| **Code Fragment Colors**:
Color-Scheme of multiline codeblocks ||| +| `--fragment-background` |
#F8F9FA | #282c34 |
+| `--fragment-foreground` | #37474F | #dbe4eb |
+| **Arrow Opacity**:By default the arrows in the sidebar are only visible on hover. You can override this behavior so they are visible all the time. ||| +| `--side-nav-arrow-opacity` | `0` | | +| `--side-nav-arrow-hover-opacity` | `0.9` | | +| ...and many more ||| If you miss a configuration option or find a bug, please consider [opening an issue](https://github.com/jothepro/doxygen-awesome-css/issues)! @@ -85,11 +92,11 @@ If you miss a configuration option or find a bug, please consider [opening an is The theme overrides most colors with the `--primary-color-*` variables. -But there is a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with +But there are a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with the rest, it is recommended to adjust the [doxygen color settings](https://www.doxygen.nl/manual/customize.html#minor_tweaks_colors) -to something that matches the chosen color-scheme. +to something that matches the chosen color scheme. -For the default color-scheme, these values work out quite well: +For the default color scheme, these values work out quite well: ``` # Doxyfile @@ -100,11 +107,15 @@ HTML_COLORSTYLE_GAMMA = 113 ## Share your customizations -If you customized the theme with custom colors, spacings, font-sizes, etc. and you want to share your creation with others, you can to this [here](https://github.com/jothepro/doxygen-awesome-css/discussions/13). +If you have customized the theme with custom colors, spacings, font-sizes, etc. and you want to share your creation with others, you can do this [here](https://github.com/jothepro/doxygen-awesome-css/discussions/13). I am always curious to learn about how you made the theme look even better! - \ No newline at end of file + \ No newline at end of file diff --git a/Docs/doxygen-awesome-css/docs/extensions.md b/Docs/doxygen-awesome-css/docs/extensions.md index 8eb82d93..ea1ce00d 100644 --- a/Docs/doxygen-awesome-css/docs/extensions.md +++ b/Docs/doxygen-awesome-css/docs/extensions.md @@ -4,7 +4,7 @@ On top of the base theme provided by `doxygen-awesome.css`, this repository comes with Javascript extensions that require additional setup steps to get them running. -The extensions require customizations in the header HTML-template. +The extensions require customizations in the header HTML template. This is how you can create the default template with Doxygen: 1. Create default header template: @@ -19,11 +19,14 @@ This is how you can create the default template with Doxygen: [More details on header customization](https://www.doxygen.nl/manual/customize.html#minor_tweaks_header_css) -## Dark Mode Toggle +## Dark Mode Toggle {#extension-dark-mode-toggle} -Adds a button next to the search bar to enable and disable the dark theme variant manually. +Adds a button next to the search bar to enable and disable the dark theme variant manually: -
+
+
+{width=250px}
+
### Installation
@@ -43,28 +46,32 @@ Adds a button next to the search bar to enable and disable the dark theme varian
```
-3. The button can be customized to some extend:
- - Change the tooltip of the button:
- ```js
- DoxygenAwesomeDarkModeToggle.title = "Zwischen hellem/dunklem Modus wechseln"
- ```
- - Change Icons. Both Emoji or SVG icons are supported:
- ```js
- DoxygenAwesomeDarkModeToggle.lightModeIcon = '🌞'
- // icon from https://fonts.google.com/icons
- DoxygenAwesomeDarkModeToggle.darkModeIcon = ``
- ```
- All customizations must be applied before calling `DoxygenAwesomeDarkModeToggle.init()`!
+### Customizing
+
+Changing the tooltip of the button:
+```js
+DoxygenAwesomeDarkModeToggle.title = "Zwischen hellem/dunklem Modus wechseln"
+```
+
+Changing Icons. Both Emoji or SVG icons are supported:
+```js
+DoxygenAwesomeDarkModeToggle.lightModeIcon = '🌞'
+// icon from https://fonts.google.com/icons
+DoxygenAwesomeDarkModeToggle.darkModeIcon = ``
+```
+All customizations must be applied before calling `DoxygenAwesomeDarkModeToggle.init()`!
-## Fragment Copy Button
-***This feature is experimental!***
+## Fragment Copy Button {#extension-copy-button}
Shows a copy button when the user hovers over a code fragment:
-
+
+
+{width=490}
+
### Installation
@@ -82,26 +89,30 @@ Shows a copy button when the user hovers over a code fragment:
```
-3. The button can be customized to some extend:
- - Change the tooltip of the button:
- ```js
- DoxygenAwesomeFragmentCopyButton.title = "In die Zwischenablage kopieren"
- ```
- - Change Icons:
- ```js
- DoxygenAwesomeFragmentCopyButton.copyIcon = `