Skip to content

Commit 51bf6d7

Browse files
dirkolbrichdirkolbrich
committed
docs: move C++ API docs to subfolder
1 parent f986b53 commit 51bf6d7

37 files changed

Lines changed: 7398 additions & 0 deletions

docs/CMakeLists.txt renamed to docs/cpp-api/CMakeLists.txt

File renamed without changes.

docs/Doxyfile renamed to docs/cpp-api/Doxyfile

File renamed without changes.

‎docs/cpp-api/assets/doxygen-awesome-css/.github/workflows/publish.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: publish
2+
on:
3+
release:
4+
types: [published]
5+
jobs:
6+
deploy:
7+
runs-on: ubuntu-20.04
8+
steps:
9+
- name: Checkout repository
10+
uses: actions/checkout@v2
11+
with:
12+
fetch-depth: 0
13+
- name: set version
14+
run: echo "PROJECT_NUMBER = `git describe --tags`" >> Doxyfile
15+
- name: Generate Documentation
16+
uses: mattnotmitt/doxygen-action@edge
17+
- name: Publish generated content to GitHub Pages
18+
uses: tsunematsu21/actions-publish-gh-pages@v1.0.2
19+
with:
20+
dir: docs/html
21+
branch: gh-pages
22+
token: ${{ secrets.ACCESS_TOKEN }}

‎docs/cpp-api/assets/doxygen-awesome-css/.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
docs/html
2+
.DS_Store
3+
.idea
4+
5+
node_modules
6+
*.tgz

‎docs/cpp-api/assets/doxygen-awesome-css/.npmignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*
2+
!doxygen-awesome*
3+

‎docs/cpp-api/assets/doxygen-awesome-css/Doxyfile‎

Lines changed: 2793 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/cpp-api/assets/doxygen-awesome-css/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2021 - 2023 jothepro
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎docs/cpp-api/assets/doxygen-awesome-css/Makefile‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# SPDX-FileCopyrightText: 2022 Andrea Pappacoda <andrea@pappacoda.it>
2+
# SPDX-License-Identifier: MIT
3+
4+
.POSIX:
5+
6+
PROJECT = doxygen-awesome-css
7+
8+
# Paths
9+
PREFIX = /usr/local
10+
DATADIR = share
11+
INSTALLDIR = $(DESTDIR)$(PREFIX)/$(DATADIR)/$(PROJECT)
12+
13+
# Utilities
14+
INSTALL = install -m 644
15+
MKDIR = mkdir -p
16+
RM = rm -f
17+
18+
# Files to be installed
19+
FILES = doxygen-awesome-darkmode-toggle.js \
20+
doxygen-awesome-fragment-copy-button.js \
21+
doxygen-awesome-interactive-toc.js \
22+
doxygen-awesome-paragraph-link.js \
23+
doxygen-awesome-sidebar-only-darkmode-toggle.css \
24+
doxygen-awesome-sidebar-only.css \
25+
doxygen-awesome.css
26+
27+
# Empty targets so that `make` and `make clean` do not cause errors
28+
all:
29+
clean:
30+
31+
install:
32+
$(MKDIR) $(INSTALLDIR)
33+
$(INSTALL) $(FILES) $(INSTALLDIR)/
34+
35+
uninstall:
36+
$(RM) -r $(INSTALLDIR)/
37+
38+
.PHONY: all clean install uninstall

‎docs/cpp-api/assets/doxygen-awesome-css/README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Doxygen Awesome
2+
3+
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/jothepro/doxygen-awesome-css)](https://github.com/jothepro/doxygen-awesome-css/releases/latest)
4+
[![GitHub](https://img.shields.io/github/license/jothepro/doxygen-awesome-css)](https://github.com/jothepro/doxygen-awesome-css/blob/main/LICENSE)
5+
![GitHub Repo stars](https://img.shields.io/github/stars/jothepro/doxygen-awesome-css)
6+
7+
<div class="title_screenshot">
8+
9+
![Screenshot of Doxygen Awesome CSS](img/screenshot.png)
10+
11+
</div>
12+
13+
**Doxygen Awesome** is a custom **CSS theme for Doxygen HTML-documentation** with lots of customization parameters.
14+
15+
## Motivation
16+
17+
I really like how the Doxygen HTML-documentation is structured! But IMHO it looks a bit outdated.
18+
19+
This theme is an attempt to update the visuals of Doxygen without changing its overall layout too much.
20+
21+
## Features
22+
23+
- 🌈 Clean, modern design
24+
- 🚀 Heavily customizable by adjusting CSS-variables
25+
- 🧩 No changes to the HTML structure of Doxygen required
26+
- 📱 Improved mobile usability
27+
- 🌘 Dark mode support!
28+
- 🥇 Works best with **doxygen 1.9.1** - **1.9.4** and **1.9.6** - **1.9.7**
29+
30+
## Examples
31+
32+
Some websites using this theme:
33+
34+
- [Documentation of this repository](https://jothepro.github.io/doxygen-awesome-css/)
35+
- [wxWidgets](https://docs.wxwidgets.org/3.2/)
36+
- [OpenCV 5.x](https://docs.opencv.org/5.x/)
37+
- [Zephyr](https://docs.zephyrproject.org/latest/doxygen/html/index.html)
38+
- [FELTOR](https://mwiesenberger.github.io/feltor/dg/html/modules.html)
39+
- [Spatial Audio Framework (SAF)](https://leomccormack.github.io/Spatial_Audio_Framework/index.html)
40+
- [libCloudSync](https://jothepro.github.io/libCloudSync/)
41+
- [libsl3](https://a4z.github.io/libsl3/)
42+
43+
## Installation
44+
45+
To use the theme when generating your documentation, bring the required CSS and JS files from this repository into your project.
46+
47+
This can be done in several ways:
48+
49+
- manually copying the files
50+
- adding the project as a Git submodule
51+
- adding the project as a npm/xpm dependency
52+
- installing the theme system wide
53+
54+
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.
55+
56+
### Git submodule
57+
58+
For projects which use git, add the repository as a submodule and check out the desired release:
59+
60+
```sh
61+
git submodule add https://github.com/jothepro/doxygen-awesome-css.git
62+
cd doxygen-awesome-css
63+
git checkout v2.2.1
64+
```
65+
66+
### npm/xpm dependency
67+
68+
In the npm ecosystem, this project can be added as a development dependency
69+
to your project:
70+
71+
```sh
72+
cd your-project
73+
npm install https://github.com/jothepro/doxygen-awesome-css#v2.2.1 --save-dev
74+
75+
ls -l node_module/@jothepro/doxygen-awesome-css
76+
```
77+
78+
Similarly, in the [xPack](https://xpack.github.io) ecosystem, this project can be added
79+
as a development dependency to an [`xpm`](https://xpack.github.io/xpm/)
80+
managed project.
81+
82+
### System-wide
83+
84+
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`.
85+
86+
### Choosing a layout
87+
88+
There is two layout options. Choose one of them and configure Doxygen accordingly:
89+
90+
<div class="darkmode_inverted_image">
91+
92+
![Available theme variants](img/theme-variants.drawio.svg)
93+
94+
</div>
95+
96+
<div class="tabbed">
97+
98+
- <b class="tab-title">1️⃣ Base Theme </b>
99+
Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled.
100+
101+
Required files: `doxygen-awesome.css`
102+
103+
Required `Doxyfile` configuration:
104+
```
105+
GENERATE_TREEVIEW = YES # optional. Also works without treeview
106+
DISABLE_INDEX = NO
107+
FULL_SIDEBAR = NO
108+
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
109+
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
110+
```
111+
112+
- <b class="tab-title">2️⃣ Sidebar-Only Theme </b>
113+
Hides the top titlebar to give more space to the content. The treeview must be enabled in order for this theme to work.
114+
115+
Required files: `doxygen-awesome.css`, `doxygen-awesome-sidebar-only.css`
116+
117+
Required `Doxyfile` configuration:
118+
```
119+
120+
GENERATE_TREEVIEW = YES # required!
121+
DISABLE_INDEX = NO
122+
FULL_SIDEBAR = NO
123+
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \
124+
doxygen-awesome-css/doxygen-awesome-sidebar-only.css
125+
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
126+
```
127+
128+
</div>
129+
130+
**Caution**:
131+
- This theme is not compatible with the `FULL_SIDEBAR = YES` option provided by Doxygen!
132+
- `HTML_COLORSTYLE` must be set to `LIGHT` since Doxygen 1.9.5!
133+
134+
### Further installation instructions:
135+
136+
- [Installing extensions](docs/extensions.md)
137+
- [Customizing the theme (colors, spacing, border-radius, ...)](docs/customization.md)
138+
- [Tips and Tricks for further configuration](docs/tricks.md)
139+
140+
## Browser support
141+
142+
Tested with
143+
144+
- Chrome 110, Chrome 109 for Android, Chrome 110 for iOS
145+
- Safari 16, Safari for iOS 16
146+
- Firefox 110, Firefox 110 for Android, Firefox 109 for iOS
147+
- Edge 110
148+
149+
150+
The theme does not strive to be backwards compatible to (significantly) older browser versions.
151+
152+
153+
## Credits
154+
155+
Thanks for all the bug reports and inspiring feedback on github!
156+
157+
Special thanks to all the contributors:
158+
<br><br>
159+
<a href="https://github.com/jothepro/doxygen-awesome-css/graphs/contributors">
160+
<img src="https://contrib.rocks/image?repo=jothepro/doxygen-awesome-css" />
161+
</a>
162+
163+
<span class="next_section_button">
164+
165+
Read Next: [Extensions](docs/extensions.md)
166+
</span>

‎docs/cpp-api/assets/doxygen-awesome-css/docs/customization.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Customization
2+
3+
[TOC]
4+
5+
6+
## CSS-Variables
7+
8+
This theme is highly customizable because a lot of things are parameterized with CSS variables.
9+
10+
Just to give you an idea on how flexible the styling is, click this button:
11+
12+
<div class="alter-theme-button" onclick="toggle_alternative_theme()" onkeypress="if (event.keyCode == 13) toggle_alternative_theme()" tabindex=0>Alter theme</div>
13+
14+
### Setup
15+
16+
It is recommended to add your own `custom.css` and overwrite the variables there:
17+
```
18+
HTML_EXTRA_STYLESHEET = doxygen-awesome.css custom.css
19+
```
20+
21+
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:
22+
23+
```css
24+
html {
25+
/* override light-mode variables here */
26+
}
27+
```
28+
29+
For dark-mode overrides you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not:
30+
31+
<div class="tabbed">
32+
33+
- <b class="tab-title">dark-mode toggle is installed</b>
34+
```css
35+
html.dark-mode {
36+
/* define dark-mode variable overrides here if you DO use doxygen-awesome-darkmode-toggle.js */
37+
}
38+
```
39+
- <b class="tab-title">dark-mode toggle is **NOT** installed</b>
40+
The dark-mode is enabled automatically depending on the system preference:
41+
```css
42+
@media (prefers-color-scheme: dark) {
43+
html:not(.light-mode) {
44+
/* define dark-mode variable overrides here if you DON'T use doxygen-awesome-darkmode-toggle.js */
45+
}
46+
}
47+
```
48+
49+
</div>
50+
51+
### Available variables
52+
53+
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).
54+
55+
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).
56+
All variables are defined at the beginning of the stylesheet.
57+
58+
| Parameter | Default (Light) | Default (Dark) |
59+
| :---------------------------------- | :---------------------------------------------------------- | :---------------------------------------------------------- |
60+
| **Color Scheme**:<br>primary theme colors. This will affect the entire websites color scheme: links, arrows, labels, ... |||
61+
| `--primary-color` | <code style="background:#1779c4;color:white">#1779c4</code> | <code style="background:#1982d2;color:white">#1982d2</code> |
62+
| `--primary-dark-color` | <code style="background:#335c80;color:white">#335c80</code> | <code style="background:#5ca8e2;color:black">#5ca8e2</code> |
63+
| `--primary-light-color` | <code style="background:#70b1e9;color:black">#70b1e9</code> | <code style="background:#4779ac;color:white">#4779ac</code> |
64+
| **Page Colors**:<br>background and foreground (text-color) of the documentation. |||
65+
| `--page-background-color` | <code style="background:#ffffff;color:black">#ffffff</code> | <code style="background:#1C1D1F;color:white">#1C1D1F</code> |
66+
| `--page-foreground-color` | <code style="background:#2f4153;color:white">#2f4153</code> | <code style="background:#d2dbde;color:black">#d2dbde</code> |
67+
| `--page-secondary-foreground-color` | <code style="background:#6f7e8e;color:white">#6f7e8e</code> | <code style="background:#859399;color:white">#859399</code> |
68+
| **Spacing:**<br>default spacings. Most ui components reference these values for spacing, to provide uniform spacing on the page. |||
69+
| `--spacing-small` | `5px` | |
70+
| `--spacing-medium` | `10px` | |
71+
| `--spacing-large` | `16px` | |
72+
| **Border Radius**:<br>border radius for all rounded ui components. Will affect many components, like dropdowns, memitems, codeblocks, ... |||
73+
| `--border-radius-small` | `4px` | |
74+
| `--border-radius-medium` | `6px` | |
75+
| `--border-radius-large` | `8px` | |
76+
| **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`. |||
77+
| `--content-maxwidth` | `1000px` | |
78+
| **Code Fragment Colors**:<br>Color-Scheme of multiline codeblocks |||
79+
| `--fragment-background` | <code style="background:#F8F9FA;color:black">#F8F9FA</code> | <code style="background:#282c34;color:white">#282c34</code> |
80+
| `--fragment-foreground` | <code style="background:#37474F;color:white">#37474F</code> | <code style="background:#dbe4eb;color:black">#dbe4eb</code> |
81+
| **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. |||
82+
| `--side-nav-arrow-opacity` | `0` | |
83+
| `--side-nav-arrow-hover-opacity` | `0.9` | |
84+
| ...and many more |||
85+
86+
87+
If you miss a configuration option or find a bug, please consider [opening an issue](https://github.com/jothepro/doxygen-awesome-css/issues)!
88+
89+
## Doxygen generator
90+
91+
The theme overrides most colors with the `--primary-color-*` variables.
92+
93+
But there is a few small images and graphics that the theme cannot adjust or replace. To make these blend in better with
94+
the rest, it is recommended to adjust the [doxygen color settings](https://www.doxygen.nl/manual/customize.html#minor_tweaks_colors)
95+
to something that matches the chosen color-scheme.
96+
97+
For the default color-scheme, these values work out quite well:
98+
99+
```
100+
# Doxyfile
101+
HTML_COLORSTYLE_HUE = 209
102+
HTML_COLORSTYLE_SAT = 255
103+
HTML_COLORSTYLE_GAMMA = 113
104+
```
105+
106+
## Share your customizations
107+
108+
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).
109+
110+
I am always curious to learn about how you made the theme look even better!
111+
112+
<span class="next_section_button">
113+
114+
Read Next: [Tips & Tricks](tricks.md)
115+
</span>

0 commit comments

Comments
 (0)