chris/xtree
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added doxygen files

Browse Source
This commit is contained in:
PANIK\chris
2025-09-21 12:50:15 +02:00
parent bf49d8321f
commit 2180b62bf1
38 changed files with 10723 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
doc/doxygen-awesome-css/docs/customization.md Normal file
View File

@@ -0,0 +1,121 @@
# Customization
[TOC]
## CSS-Variables
This theme is highly customizable because a lot of things are parameterized with CSS variables.
Just to give you an idea of how flexible the styling is, click this button:
<div class="alter-theme-button" onclick="toggle_alternative_theme()" onkeypress="if (event.keyCode == 13) toggle_alternative_theme()" tabindex=0>Alter theme</div>
<br><hr>
### Setup
It is recommended to add your own `custom.css` and overwrite the variables there:
```
HTML_EXTRA_STYLESHEET = doxygen-awesome.css custom.css
```
Make sure to override the variables in the correct spot. All variables should be customized where they have been defined, in the `html` tag selector:
```css
html {
/* override light-mode variables here */
}
```
For dark-mode overrides, you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not:
<div class="tabbed">
- <b class="tab-title">dark-mode toggle is installed</b>
```css
html.dark-mode {
/* define dark-mode variable overrides here if you DO use doxygen-awesome-darkmode-toggle.js */
}
```
- <b class="tab-title">dark-mode toggle is **NOT** installed</b>
The dark-mode is enabled automatically depending on the system preference:
```css
@media (prefers-color-scheme: dark) {
html:not(.light-mode) {
/* define dark-mode variable overrides here if you DON'T use doxygen-awesome-darkmode-toggle.js */
}
}
```
</div>
### 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).
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**:<br>primary theme colors. This will affect the entire websites color scheme: links, arrows, labels, ... |||
| `--primary-color` | <code style="background:#1779c4;color:white">#1779c4</code> | <code style="background:#1982d2;color:white">#1982d2</code> |
| `--primary-dark-color` | <code style="background:#335c80;color:white">#335c80</code> | <code style="background:#5ca8e2;color:black">#5ca8e2</code> |
| `--primary-light-color` | <code style="background:#70b1e9;color:black">#70b1e9</code> | <code style="background:#4779ac;color:white">#4779ac</code> |
| **Page Colors**:<br>background and foreground (text-color) of the documentation. |||
| `--page-background-color` | <code style="background:#ffffff;color:black">#ffffff</code> | <code style="background:#1C1D1F;color:white">#1C1D1F</code> |
| `--page-foreground-color` | <code style="background:#2f4153;color:white">#2f4153</code> | <code style="background:#d2dbde;color:black">#d2dbde</code> |
| `--page-secondary-foreground-color` | <code style="background:#6f7e8e;color:white">#6f7e8e</code> | <code style="background:#859399;color:white">#859399</code> |
| **Spacing:**<br>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**:<br>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**:<br>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**:<br>Color-Scheme of multiline codeblocks |||
| `--fragment-background` | <code style="background:#F8F9FA;color:black">#F8F9FA</code> | <code style="background:#282c34;color:white">#282c34</code> |
| `--fragment-foreground` | <code style="background:#37474F;color:white">#37474F</code> | <code style="background:#dbe4eb;color:black">#dbe4eb</code> |
| **Arrow Opacity**:<br>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)!
## Doxygen generator
The theme overrides most colors with the `--primary-color-*` variables.
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.
For the default color scheme, these values work out quite well:
```
# Doxyfile
HTML_COLORSTYLE_HUE = 209
HTML_COLORSTYLE_SAT = 255
HTML_COLORSTYLE_GAMMA = 113
```
## Share your customizations
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!
<div class="section_buttons">
| Previous | Next |
|:----------------------------|---------------------------:|
| [Extensions](extensions.md) | [Tips & Tricks](tricks.md) |
</div>

284
doc/doxygen-awesome-css/docs/extensions.md Normal file
View File

@@ -0,0 +1,284 @@
# Extensions
[TOC]
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.
This is how you can create the default template with Doxygen:
1. Create default header template:
```sh
doxygen -w html header.html delete_me.html delete_me.css
```
2. Reference the template in your `Doxyfile`:
```
HTML_HEADER = header.html
```
[More details on header customization](https://www.doxygen.nl/manual/customize.html#minor_tweaks_header_css)
## Dark Mode Toggle {#extension-dark-mode-toggle}
Adds a button next to the search bar to enable and disable the dark theme variant manually:
<div class="darkmode_inverted_image bordered_image">
![](img/darkmode_toggle.png){width=250px}
</div>
### Installation
1. Add the required resources in your `Doxyfile`:
- **HTML_EXTRA_FILES:** `doxygen-awesome-darkmode-toggle.js`
- **HTML_EXTRA_STYLESHEET:** `doxygen-awesome-sidebar-only-darkmode-toggle.css`
<em>(ONLY required for the sidebar-only theme variant!)</em>
2. In the `header.html` template, include `doxygen-awesome-darkmode-toggle.js` at the end of the `<head>` and then initialize it:
```html
<html>
<head>
<!-- ... other metadata & script includes ... -->
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
DoxygenAwesomeDarkModeToggle.init()
</script>
</head>
<body>
```
### 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 = `<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#009793"><g><rect fill="none" height="24" width="24"/></g><g><g><path d="M8.1,14.15C9.77,14.63,11,16.17,11,18c0,0.68-0.19,1.31-0.48,1.87c0.48,0.09,0.97,0.14,1.48,0.14 c1.48,0,2.9-0.41,4.13-1.15c-2.62-0.92-5.23-2.82-6.8-5.86C7.74,9.94,7.78,7.09,8.29,4.9c-2.57,1.33-4.3,4.01-4.3,7.1c0,0,0,0,0,0 c0.01,0,0.01,0,0.02,0C5.66,12,7.18,12.83,8.1,14.15z" opacity=".3"/><path d="M19.78,17.51c-2.47,0-6.57-1.33-8.68-5.43C8.77,7.57,10.6,3.6,11.63,2.01C6.27,2.2,1.98,6.59,1.98,12 c0,0.14,0.02,0.28,0.02,0.42C2.61,12.16,3.28,12,3.98,12c0,0,0,0,0,0c0-3.09,1.73-5.77,4.3-7.1C7.78,7.09,7.74,9.94,9.32,13 c1.57,3.04,4.18,4.95,6.8,5.86c-1.23,0.74-2.65,1.15-4.13,1.15c-0.5,0-1-0.05-1.48-0.14c-0.37,0.7-0.94,1.27-1.64,1.64 c0.98,0.32,2.03,0.5,3.11,0.5c3.5,0,6.58-1.8,8.37-4.52C20.18,17.5,19.98,17.51,19.78,17.51z"/><path d="M7,16l-0.18,0C6.4,14.84,5.3,14,4,14c-1.66,0-3,1.34-3,3s1.34,3,3,3c0.62,0,2.49,0,3,0c1.1,0,2-0.9,2-2 C9,16.9,8.1,16,7,16z"/></g></g></svg>`
```
All customizations must be applied before calling `DoxygenAwesomeDarkModeToggle.init()`!
## Fragment Copy Button {#extension-copy-button}
Shows a copy button when the user hovers over a code fragment:
<div class="darkmode_inverted_image bordered_image">
![](img/fragment_copy_button.png){width=490}
</div>
### Installation
1. Add the required resources in your `Doxyfile`:
- **HTML_EXTRA_FILES:** `doxygen-awesome-fragment-copy-button.js`
- **HTML_COPY_CLIPBOARD:** `NO` required with Doxygen >= 1.10.0
2. In the `header.html` template, include `doxygen-awesome-fragment-copy-button.js` at the end of the `<head>` and then initialize it:
```html
<html>
<head>
<!-- ... other metadata & script includes ... -->
<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
<script type="text/javascript">
DoxygenAwesomeFragmentCopyButton.init()
</script>
</head>
<body>
```
### Customizing
The tooltip of the button can be changed:
```js
DoxygenAwesomeFragmentCopyButton.title = "In die Zwischenablage kopieren"
```
The icon can be changed. It must be an SVG:
```js
DoxygenAwesomeFragmentCopyButton.copyIcon = `<svg ...>`
DoxygenAwesomeFragmentCopyButton.successIcon = `<svg ...>`
```
All customizations must be applied before calling `DoxygenAwesomeDarkModeToggle.init()`!
## Paragraph Linking {#extension-para}
Provides a button on hover behind every headline to allow easy creation of a permanent link to the headline:
<div class="darkmode_inverted_image bordered_image">
![](img/paragraph_link.png){width=220}
</div>
Works for all headlines and for many documentation section titles.
### Installation
1. Add the required resources in your `Doxyfile`:
- **HTML_EXTRA_FILES:** `doxygen-awesome-paragraph-link.js`
2. In the `header.html` template, include `doxygen-awesome-paragraph-link.js` at the end of the `<head>` and then initialize it:
```html
<html>
<head>
<!-- ... other metadata & script includes ... -->
<script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
<script type="text/javascript">
DoxygenAwesomeParagraphLink.init()
</script>
</head>
<body>
```
### Customizing
The button tooltip can be changed:
```js
DoxygenAwesomeParagraphLink.title = "Abschnitt verknüpfen"
```
The icon of the button can be changed. Both plain characters or SVG icons are supported:
```js
DoxygenAwesomeParagraphLink.icon = "¶"
```
All customizations must be applied before calling `DoxygenAwesomeParagraphLink.init()`!
## Interactive TOC {#extension-toc}
On large screens, the Table of Contents (TOC) is anchored on the top right of the page. This extension visualizes the reading progress by dynamically highlighting the currently active section.
On small screens, the extension hides the TOC by default. The user can open it manually when needed:
<div class="darkmode_inverted_image bordered_image">
![](img/interactive_toc_mobile.png){width=380}
</div>
### Installation
1. Add the required resources in your `Doxyfile`:
- **HTML_EXTRA_FILES:** `doxygen-awesome-interactive-toc.js`
2. In the `header.html` template, include `doxygen-awesome-interactive-toc.js` at the end of the `<head>` and then initialize it:
```html
<html>
<head>
<!-- ... other metadata & script includes ... -->
<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
<script type="text/javascript">
DoxygenAwesomeInteractiveToc.init()
</script>
</head>
<body>
```
### Customizing
The offset for when a headline is considered active can be changed. A smaller value means that the headline of the section must be closer to the top of the viewport before it is highlighted in the TOC:
```js
DoxygenAwesomeInteractiveToc.topOffset = 45
```
Hiding the TOC on small screens can be disabled. It is still interactive and can be hidden by the user but will now be open by default:
```js
DoxygenAwesomeInteractiveToc.hideMobileMenu = false
```
## Tabs {#extension-tabs}
@warning Experimental feature! Please report bugs [here](https://github.com/jothepro/doxygen-awesome-css/issues).
This extension allows to arrange list content in tabs:
<div class="tabbed">
- <b class="tab-title">Tab 1</b>
This is the content of tab 1
- <b class="tab-title">Tab 2</b>
This is the content of tab 2
1. it has a list
2. with multiple items
</div>
### Installation
1. Add the required resources in your `Doxyfile`:
- **HTML_EXTRA_FILES:** `doxygen-awesome-tabs.js`
2. In the `header.html` template, include `doxygen-awesome-tabs.js` at the end of the `<head>` and then initialize it:
```html
<html>
<head>
<!-- ... other metadata & script includes ... -->
<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
<script type="text/javascript">
DoxygenAwesomeTabs.init()
</script>
</head>
<body>
```
### Usage
Each list that is supposed to be displayed as tabs has to be wrapped with the `tabbed` CSS class.
Each item in the list must start with an element that has the class `tab-title`. It will then be used as tab title.
```md
<div class="tabbed">
- <b class="tab-title">Tab 1</b> This is the content of tab 1
- <b class="tab-title">Tab 2</b> This is the content of tab 2
</div>
```
## Page Navigation {#extension-page-navigation}
@warning Experimental feature! Please report bugs [here](https://github.com/jothepro/doxygen-awesome-css/issues).
To allow the user to easily navigate from one document to another, "Next" and "Previous" buttons can be added at the end of a Markdown document.
### Installation
The feature is shipped inside the default `doxygen-awesome.css`. No additional stylesheets or scripts need to be added.
### Usage
The following conditions must be met for the feature to work properly:
- The navigation must be inside a Markdown table with 1-2 columns.
- The alignment of the column defines the alignment of the arrow on the navigation button.
- the table must be wrapped inside a `<div>` with the class `section_buttons`.
<div class="tabbed">
- <span class="tab-title">Code</span>
```md
<div class="section_buttons">
| Previous | Next |
|:------------------|----------------------------------:|
| [Home](README.md) | [Customization](customization.md) |
</div>
```
- <span class="tab-title">Result</span>
<div class="section_buttons">
| Previous | Next |
|:------------------|----------------------------------:|
| [Home](README.md) | [Customization](customization.md) |
</div>
</div>
<div class="section_buttons">
| Previous | Next |
|:------------------|----------------------------------:|
| [Home](README.md) | [Customization](customization.md) |
</div>

BIN
doc/doxygen-awesome-css/docs/img/darkmode_toggle.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
doc/doxygen-awesome-css/docs/img/fancy_scrollbars_firefox.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
doc/doxygen-awesome-css/docs/img/fancy_scrollbars_webkit.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.4 MiB

BIN
doc/doxygen-awesome-css/docs/img/fragment_copy_button.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
doc/doxygen-awesome-css/docs/img/interactive_toc_mobile.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/doxygen-awesome-css/docs/img/paragraph_link.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

127
doc/doxygen-awesome-css/docs/tricks.md Normal file
View File

@@ -0,0 +1,127 @@
# Tips & Tricks
[TOC]
## Diagrams with Graphviz {#tricks-graphviz}
To get the best-looking class diagrams for your documentation, generate them with Graphviz as vector graphics with transparent background:
```
# Doxyfile
HAVE_DOT = YES
DOT_IMAGE_FORMAT = svg
DOT_TRANSPARENT = YES
```
In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, all user-defined dotgraphs must be wrapped with the `interactive_dotgraph` CSS class for them to be rendered correctly:
```md
<div class="interactive_dotgraph">
\dotfile graph.dot
</div>
```
@note Both the default overflow scrolling behavior in this theme and the interactive editor enabled by `INTERACTIVE_SVG` are unsatisfying workarounds IMHO. Consider designing your graphs to be narrow enough to fit the page to avoid scrolling.
## Disable Dark Mode {#tricks-darkmode}
If you don't want the theme to automatically switch to dark mode depending on the browser preference,
you can disable dark mode by adding the `light-mode` class to the HTML tag in the header template:
```html
<html xmlns="http://www.w3.org/1999/xhtml" class="light-mode">
```
The same can be done to always enable dark mode:
```html
<html xmlns="http://www.w3.org/1999/xhtml" class="dark-mode">
```
@warning This only works if you don't use the dark-mode toggle extension.
## Choosing Sidebar Width {#tricks-sidebar}
If you have enabled the sidebar-only theme variant, make sure to carefully choose a proper width for your sidebar.
It should be wide enough to hold the icon, project title and version number. If the content is too wide, it will be
cut off.
```css
html {
/* Make sure sidebar is wide enough to contain the page title (logo + title + version) */
--side-nav-fixed-width: 335px;
}
```
The chosen width should also be set in the Doxyfile:
```
# Doxyfile
TREEVIEW_WIDTH = 335
```
## Formatting Tables {#tricks-tables}
By default tables in this theme are left-aligned and as wide as required to fit their content.
Those properties can be changed for individual tables.
### Centering
Tables can be centered by wrapping them in the `<center>` HTML tag.
<div class="tabbed">
- <span class="tab-title">Code</span>
```md
<center>
| This table | is centered |
|------------|----------------------|
| test 1 | test 2 |
</center>
```
- <span class="tab-title">Result</span>
<center>
| This table | is centered |
|------------|----------------------|
| test 1 | test 2 |
</center>
</div>
### Full Width
To make tables span the full width of the page, no matter how wide the content is, wrap the table in the `full_width_table` CSS class.
@warning Apply with caution! This breaks the overflow scrolling of the table. Content might be cut off on small screens!
<div class="tabbed">
- <span class="tab-title">Code</span>
```md
<div class="full_width_table">
| This table | spans the full width |
|------------|----------------------|
| test 1 | test 2 |
</div>
```
- <span class="tab-title">Result</span>
<div class="full_width_table">
| This table | spans the full width |
|------------|----------------------|
| test 1 | test 2 |
</div>
</div>
<div class="section_buttons">
| Previous | Next |
|:----------------------------------|---------------------------------------:|
| [Customization](customization.md) | [Example](https://jothepro.github.io/doxygen-awesome-css/class_my_library_1_1_example.html) |
</div>