Skip to content

Commit 906cfb2

Browse files
committed
Documentation improvments
1 parent 5ba00c5 commit 906cfb2

5 files changed

Lines changed: 411 additions & 2 deletions

File tree

doxygen/Doxyfile

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1355,7 +1355,7 @@ HTML_FILE_EXTENSION = .html
13551355
# of the possible markers and block names see the documentation.
13561356
# This tag requires that the tag GENERATE_HTML is set to YES.
13571357

1358-
HTML_HEADER =
1358+
HTML_HEADER = html/header.html
13591359

13601360
# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
13611361
# generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1406,7 +1406,10 @@ HTML_EXTRA_STYLESHEET = stylesheets/doxygen-awesome.css \
14061406
# files will be copied as-is; there are no commands or markers available.
14071407
# This tag requires that the tag GENERATE_HTML is set to YES.
14081408

1409-
HTML_EXTRA_FILES = assets/github-mark-white.svg
1409+
HTML_EXTRA_FILES = assets/github-mark-white.svg \
1410+
js/doxygen-awesome-darkmode-toggle.js \
1411+
js/doxygen-awesome-fragment-copy-button.js \
1412+
js/doxygen-awesome-interactive-toc.js
14101413

14111414
# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
14121415
# should be rendered with a dark or light theme.

doxygen/html/header.html

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<!-- HTML header for doxygen 1.9.7-->
2+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3+
<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
4+
<head>
5+
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
6+
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
7+
<meta name="generator" content="Doxygen $doxygenversion"/>
8+
<meta name="viewport" content="width=device-width, initial-scale=1"/>
9+
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
10+
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
11+
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
12+
<!--BEGIN DISABLE_INDEX-->
13+
<!--BEGIN FULL_SIDEBAR-->
14+
<script type="text/javascript">var page_layout=1;</script>
15+
<!--END FULL_SIDEBAR-->
16+
<!--END DISABLE_INDEX-->
17+
<script type="text/javascript" src="$relpath^jquery.js"></script>
18+
<script type="text/javascript" src="$relpath^dynsections.js"></script>
19+
$treeview
20+
$search
21+
$mathjax
22+
$darkmode
23+
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
24+
$extrastylesheet
25+
26+
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
27+
<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
28+
<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
29+
<script type="text/javascript">
30+
DoxygenAwesomeDarkModeToggle.init();
31+
DoxygenAwesomeFragmentCopyButton.init();
32+
DoxygenAwesomeInteractiveToc.init();
33+
</script>
34+
</head>
35+
<body>
36+
<!--BEGIN DISABLE_INDEX-->
37+
<!--BEGIN FULL_SIDEBAR-->
38+
<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
39+
<!--END FULL_SIDEBAR-->
40+
<!--END DISABLE_INDEX-->
41+
42+
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
43+
44+
<!--BEGIN TITLEAREA-->
45+
<div id="titlearea">
46+
<table cellspacing="0" cellpadding="0">
47+
<tbody>
48+
<tr id="projectrow">
49+
<!--BEGIN PROJECT_LOGO-->
50+
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
51+
<!--END PROJECT_LOGO-->
52+
<!--BEGIN PROJECT_NAME-->
53+
<td id="projectalign">
54+
<div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
55+
</div>
56+
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
57+
</td>
58+
<!--END PROJECT_NAME-->
59+
<!--BEGIN !PROJECT_NAME-->
60+
<!--BEGIN PROJECT_BRIEF-->
61+
<td>
62+
<div id="projectbrief">$projectbrief</div>
63+
</td>
64+
<!--END PROJECT_BRIEF-->
65+
<!--END !PROJECT_NAME-->
66+
<!--BEGIN DISABLE_INDEX-->
67+
<!--BEGIN SEARCHENGINE-->
68+
<!--BEGIN !FULL_SIDEBAR-->
69+
<td>$searchbox</td>
70+
<!--END !FULL_SIDEBAR-->
71+
<!--END SEARCHENGINE-->
72+
<!--END DISABLE_INDEX-->
73+
</tr>
74+
<!--BEGIN SEARCHENGINE-->
75+
<!--BEGIN FULL_SIDEBAR-->
76+
<tr><td colspan="2">$searchbox</td></tr>
77+
<!--END FULL_SIDEBAR-->
78+
<!--END SEARCHENGINE-->
79+
</tbody>
80+
</table>
81+
</div>
82+
<!--END TITLEAREA-->
83+
<!-- end header part -->
Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
/**
2+
3+
Doxygen Awesome
4+
https://github.com/jothepro/doxygen-awesome-css
5+
6+
MIT License
7+
8+
Copyright (c) 2021 - 2023 jothepro
9+
10+
Permission is hereby granted, free of charge, to any person obtaining a copy
11+
of this software and associated documentation files (the "Software"), to deal
12+
in the Software without restriction, including without limitation the rights
13+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14+
copies of the Software, and to permit persons to whom the Software is
15+
furnished to do so, subject to the following conditions:
16+
17+
The above copyright notice and this permission notice shall be included in all
18+
copies or substantial portions of the Software.
19+
20+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26+
SOFTWARE.
27+
28+
*/
29+
30+
class DoxygenAwesomeDarkModeToggle extends HTMLElement {
31+
// SVG icons from https://fonts.google.com/icons
32+
// Licensed under the Apache 2.0 license:
33+
// https://www.apache.org/licenses/LICENSE-2.0.html
34+
static lightModeIcon = `<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="#FCBF00"><rect fill="none" height="24" width="24"/><circle cx="12" cy="12" opacity=".3" r="3"/><path d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg>`
35+
static 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="#FE9700"><rect fill="none" height="24" width="24"/><path d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27 C17.45,17.19,14.93,19,12,19c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z" opacity=".3"/><path d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg>`
36+
static title = "Toggle Light/Dark Mode"
37+
38+
static prefersLightModeInDarkModeKey = "prefers-light-mode-in-dark-mode"
39+
static prefersDarkModeInLightModeKey = "prefers-dark-mode-in-light-mode"
40+
41+
static _staticConstructor = function() {
42+
DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.userPreference)
43+
// Update the color scheme when the browsers preference changes
44+
// without user interaction on the website.
45+
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
46+
DoxygenAwesomeDarkModeToggle.onSystemPreferenceChanged()
47+
})
48+
// Update the color scheme when the tab is made visible again.
49+
// It is possible that the appearance was changed in another tab
50+
// while this tab was in the background.
51+
document.addEventListener("visibilitychange", visibilityState => {
52+
if (document.visibilityState === 'visible') {
53+
DoxygenAwesomeDarkModeToggle.onSystemPreferenceChanged()
54+
}
55+
});
56+
}()
57+
58+
static init() {
59+
$(function() {
60+
$(document).ready(function() {
61+
const toggleButton = document.createElement('doxygen-awesome-dark-mode-toggle')
62+
toggleButton.title = DoxygenAwesomeDarkModeToggle.title
63+
toggleButton.updateIcon()
64+
65+
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
66+
toggleButton.updateIcon()
67+
})
68+
document.addEventListener("visibilitychange", visibilityState => {
69+
if (document.visibilityState === 'visible') {
70+
toggleButton.updateIcon()
71+
}
72+
});
73+
74+
$(document).ready(function(){
75+
document.getElementById("MSearchBox").parentNode.appendChild(toggleButton)
76+
})
77+
$(window).resize(function(){
78+
document.getElementById("MSearchBox").parentNode.appendChild(toggleButton)
79+
})
80+
})
81+
})
82+
}
83+
84+
constructor() {
85+
super();
86+
this.onclick=this.toggleDarkMode
87+
}
88+
89+
/**
90+
* @returns `true` for dark-mode, `false` for light-mode system preference
91+
*/
92+
static get systemPreference() {
93+
return window.matchMedia('(prefers-color-scheme: dark)').matches
94+
}
95+
96+
/**
97+
* @returns `true` for dark-mode, `false` for light-mode user preference
98+
*/
99+
static get userPreference() {
100+
return (!DoxygenAwesomeDarkModeToggle.systemPreference && localStorage.getItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey)) ||
101+
(DoxygenAwesomeDarkModeToggle.systemPreference && !localStorage.getItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey))
102+
}
103+
104+
static set userPreference(userPreference) {
105+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = userPreference
106+
if(!userPreference) {
107+
if(DoxygenAwesomeDarkModeToggle.systemPreference) {
108+
localStorage.setItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey, true)
109+
} else {
110+
localStorage.removeItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey)
111+
}
112+
} else {
113+
if(!DoxygenAwesomeDarkModeToggle.systemPreference) {
114+
localStorage.setItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey, true)
115+
} else {
116+
localStorage.removeItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey)
117+
}
118+
}
119+
DoxygenAwesomeDarkModeToggle.onUserPreferenceChanged()
120+
}
121+
122+
static enableDarkMode(enable) {
123+
if(enable) {
124+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = true
125+
document.documentElement.classList.add("dark-mode")
126+
document.documentElement.classList.remove("light-mode")
127+
} else {
128+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = false
129+
document.documentElement.classList.remove("dark-mode")
130+
document.documentElement.classList.add("light-mode")
131+
}
132+
}
133+
134+
static onSystemPreferenceChanged() {
135+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = DoxygenAwesomeDarkModeToggle.userPreference
136+
DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.darkModeEnabled)
137+
}
138+
139+
static onUserPreferenceChanged() {
140+
DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.darkModeEnabled)
141+
}
142+
143+
toggleDarkMode() {
144+
DoxygenAwesomeDarkModeToggle.userPreference = !DoxygenAwesomeDarkModeToggle.userPreference
145+
this.updateIcon()
146+
}
147+
148+
updateIcon() {
149+
if(DoxygenAwesomeDarkModeToggle.darkModeEnabled) {
150+
this.innerHTML = DoxygenAwesomeDarkModeToggle.darkModeIcon
151+
} else {
152+
this.innerHTML = DoxygenAwesomeDarkModeToggle.lightModeIcon
153+
}
154+
}
155+
}
156+
157+
customElements.define("doxygen-awesome-dark-mode-toggle", DoxygenAwesomeDarkModeToggle);
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
/**
2+
3+
Doxygen Awesome
4+
https://github.com/jothepro/doxygen-awesome-css
5+
6+
MIT License
7+
8+
Copyright (c) 2022 - 2023 jothepro
9+
10+
Permission is hereby granted, free of charge, to any person obtaining a copy
11+
of this software and associated documentation files (the "Software"), to deal
12+
in the Software without restriction, including without limitation the rights
13+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14+
copies of the Software, and to permit persons to whom the Software is
15+
furnished to do so, subject to the following conditions:
16+
17+
The above copyright notice and this permission notice shall be included in all
18+
copies or substantial portions of the Software.
19+
20+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26+
SOFTWARE.
27+
28+
*/
29+
30+
class DoxygenAwesomeFragmentCopyButton extends HTMLElement {
31+
constructor() {
32+
super();
33+
this.onclick=this.copyContent
34+
}
35+
static title = "Copy to clipboard"
36+
static copyIcon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z"/></svg>`
37+
static successIcon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41L9 16.17z"/></svg>`
38+
static successDuration = 980
39+
static init() {
40+
$(function() {
41+
$(document).ready(function() {
42+
if(navigator.clipboard) {
43+
const fragments = document.getElementsByClassName("fragment")
44+
for(const fragment of fragments) {
45+
const fragmentWrapper = document.createElement("div")
46+
fragmentWrapper.className = "doxygen-awesome-fragment-wrapper"
47+
const fragmentCopyButton = document.createElement("doxygen-awesome-fragment-copy-button")
48+
fragmentCopyButton.innerHTML = DoxygenAwesomeFragmentCopyButton.copyIcon
49+
fragmentCopyButton.title = DoxygenAwesomeFragmentCopyButton.title
50+
51+
fragment.parentNode.replaceChild(fragmentWrapper, fragment)
52+
fragmentWrapper.appendChild(fragment)
53+
fragmentWrapper.appendChild(fragmentCopyButton)
54+
55+
}
56+
}
57+
})
58+
})
59+
}
60+
61+
62+
copyContent() {
63+
const content = this.previousSibling.cloneNode(true)
64+
// filter out line number from file listings
65+
content.querySelectorAll(".lineno, .ttc").forEach((node) => {
66+
node.remove()
67+
})
68+
let textContent = content.textContent
69+
// remove trailing newlines that appear in file listings
70+
let numberOfTrailingNewlines = 0
71+
while(textContent.charAt(textContent.length - (numberOfTrailingNewlines + 1)) == '\n') {
72+
numberOfTrailingNewlines++;
73+
}
74+
textContent = textContent.substring(0, textContent.length - numberOfTrailingNewlines)
75+
navigator.clipboard.writeText(textContent);
76+
this.classList.add("success")
77+
this.innerHTML = DoxygenAwesomeFragmentCopyButton.successIcon
78+
window.setTimeout(() => {
79+
this.classList.remove("success")
80+
this.innerHTML = DoxygenAwesomeFragmentCopyButton.copyIcon
81+
}, DoxygenAwesomeFragmentCopyButton.successDuration);
82+
}
83+
}
84+
85+
customElements.define("doxygen-awesome-fragment-copy-button", DoxygenAwesomeFragmentCopyButton)

0 commit comments

Comments
 (0)