Skip to content

Commit 8a96b8d

Browse files
PoofjuniorPoofjunior
authored
Merge pull request #56 from harp-tech/dev/docs-refresh
Add documentation CI/CD workflow and update Doxygen CSS theme
2 parents bc005fd + e4cd991 commit 8a96b8d

20 files changed

Lines changed: 3155 additions & 5710 deletions

‎.github/workflows/docs.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Build and publish documentation
2+
on:
3+
push:
4+
# This prevents tag pushes from triggering this workflow
5+
branches: ['**']
6+
pull_request:
7+
release:
8+
types: [published]
9+
workflow_dispatch:
10+
inputs:
11+
publish-docs-website:
12+
description: "Publish docs website to GitHub Pages?"
13+
default: "false"
14+
jobs:
15+
# =====================================================================================================================================================================
16+
# Build documentation
17+
# =====================================================================================================================================================================
18+
build-documentation:
19+
name: Build documentation
20+
runs-on: ubuntu-latest
21+
steps:
22+
# ----------------------------------------------------------------------- Checkout
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
with:
26+
submodules: recursive
27+
28+
# ----------------------------------------------------------------------- Set up tools
29+
- name: Restore tool cache
30+
id: tool-cache
31+
uses: actions/cache@v4
32+
with:
33+
path: |
34+
doxygen-1.12.0.linux.bin.tar.gz
35+
key: doxygen-1.12.0
36+
37+
# We don't use apt to acquire Doxygen because the version provided by Ubuntu is far too old
38+
- name: Download tools
39+
if: steps.tool-cache.outputs.cache-hit != 'true'
40+
run: |
41+
wget --no-verbose https://github.com/doxygen/doxygen/releases/download/Release_1_12_0/doxygen-1.12.0.linux.bin.tar.gz
42+
echo "3c42c3f3fb206732b503862d9c9c11978920a8214f223a3950bbf2520be5f647 doxygen-1.12.0.linux.bin.tar.gz" | sha256sum --check --strict
43+
44+
- name: Install Doxygen
45+
run: |
46+
tar -xf doxygen-1.12.0.linux.bin.tar.gz
47+
echo "$(pwd)/doxygen-1.12.0/bin" >> "$GITHUB_PATH"
48+
49+
- name: Install Graphviz
50+
run: |
51+
sudo apt-get update
52+
sudo apt-get install -y graphviz
53+
54+
# ----------------------------------------------------------------------- Build documentation
55+
- name: Build documentation
56+
id: build-documentation
57+
working-directory: docs
58+
run: doxygen
59+
60+
# ----------------------------------------------------------------------- Collect artifacts
61+
- name: Collect documentation website artifact
62+
uses: actions/upload-pages-artifact@v3
63+
if: steps.build-documentation.outcome == 'success' && always()
64+
with:
65+
path: docs/doc_out/html/
66+
67+
# =====================================================================================================================================================================
68+
# Publish documentation
69+
# =====================================================================================================================================================================
70+
publish-documentation:
71+
name: Publish documentation
72+
runs-on: ubuntu-latest
73+
needs: [build-documentation]
74+
permissions:
75+
# Both required by actions/deploy-pages
76+
pages: write
77+
id-token: write
78+
environment:
79+
name: documentation-website
80+
url: ${{steps.publish.outputs.page_url}}
81+
if: |
82+
github.event_name == 'release'
83+
|| (github.event_name == 'workflow_dispatch' && github.event.inputs.publish-docs-website == 'true')
84+
|| (github.event_name == 'push' && vars.CONTINUOUS_DOCUMENTATION)
85+
steps:
86+
# ----------------------------------------------------------------------- Publish to GitHub Pages
87+
- name: Publish to GitHub Pages
88+
id: publish
89+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# files created for compiling the code
22
build/
3-
docs/*/doc_out
3+
docs/doc_out
44

55
# Kicad-generated
66
*-backups/

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ Press-and-hold the Pico's BOOTSEL button and power it up (i.e: plug it into usb)
8787
At this point you do one of the following:
8888
* drag-and-drop the created **\*.uf2** file into the mass storage device that appears on your pc.
8989
* flash with [picotool](https://github.com/raspberrypi/picotool)
90+
9091
---
9192

9293
# Using Bonsai
@@ -99,6 +100,7 @@ For more information on reading data or writing commands to your custom new harp
99100
* Several utility functions to convert betweeen local and system time exist
100101
* if events from *Harp Time* need to be scheduled in *system time*.
101102
* if events in system time need to be timestamped in *Harp time*.
103+
102104
---
103105
# Developer Notes
104106

‎docs/Doxyfile‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Difference with default Doxyfile 1.12.0 (c73f5d30f9e8b1df5ba15a1d064ff2067cbb8267)
2+
PROJECT_NAME = "Pico Core"
3+
PROJECT_LOGO = icon.png
4+
PROJECT_ICON = favicon.ico
5+
OUTPUT_DIRECTORY = doc_out
6+
STRIP_FROM_PATH = ../
7+
EXTRACT_ALL = YES
8+
EXTRACT_PRIVATE = YES
9+
EXTRACT_PRIV_VIRTUAL = YES
10+
EXTRACT_STATIC = YES
11+
CASE_SENSE_NAMES = YES
12+
INPUT = ../README.md ../firmware
13+
RECURSIVE = YES
14+
USE_MDFILE_AS_MAINPAGE = README.md
15+
HTML_HEADER = template/custom_header.html
16+
HTML_FOOTER = template/custom_footer.html
17+
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
18+
HTML_EXTRA_FILES = doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \
19+
doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
20+
HTML_COLORSTYLE = LIGHT
21+
GENERATE_TREEVIEW = YES
22+
USE_MATHJAX = YES
23+
GENERATE_LATEX = NO
24+
HAVE_DOT = YES
25+
DOT_IMAGE_FORMAT = svg

‎docs/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## Prerequisites
2+
[Doxygen](https://doxygen.nl/) and [Graphviz](https://graphviz.org/) must first be installed.
3+
4+
To build the documentation, invoke:
5+
````
6+
doxygen
7+
````

‎docs/doxygen-awesome-css/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Files in this subdirectory are from the [Doxygen Awesome][1] CSS theme
2+
and are licensed under the MIT license.
3+
4+
Copyright (c) 2021 - 2023 jothepro
5+
6+
[1]: https://github.com/jothepro/doxygen-awesome-css

‎docs/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js‎

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);

‎docs/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js‎

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)