From bfa7d02e14ff39801d5bdf92f3ca71dc0518dc76 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Tue, 25 Nov 2025 04:11:50 -0800 Subject: [PATCH 1/3] docs: revise CI corresponds to nRF24/.github#23 But really this repo just uses CI to deploy docs. So, I updated the docs sources to work better with doxygen v1.15.0 And I found/fixed a typo. --- .gitattributes | 52 +++--- .github/workflows/doxygen.yml | 32 +++- README.md | 2 - RF24Audio.h | 17 +- docs/Doxyfile | 39 ++++- docs/doxygen-custom.css | 163 ++++++++++++++++++ {images => docs/images}/NRF1.jpg | Bin {images => docs/images}/NRF2.jpg | Bin .../images}/RF24AudioBasic_LargeAntenna.jpg | Bin .../images}/RF24AudioBasic_SmallAntenna.jpg | Bin {images => docs/images}/RF24Audio_FullSD.jpg | Bin docs/images/favicon.ico | Bin 0 -> 4286 bytes docs/main_page.md | 54 +++--- docs/setup.md | 19 ++ 14 files changed, 306 insertions(+), 72 deletions(-) rename {images => docs/images}/NRF1.jpg (100%) rename {images => docs/images}/NRF2.jpg (100%) rename {images => docs/images}/RF24AudioBasic_LargeAntenna.jpg (100%) rename {images => docs/images}/RF24AudioBasic_SmallAntenna.jpg (100%) rename {images => docs/images}/RF24Audio_FullSD.jpg (100%) create mode 100644 docs/images/favicon.ico create mode 100644 docs/setup.md diff --git a/.gitattributes b/.gitattributes index e01356c..df5f001 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,26 +1,30 @@ -# Auto detect text files and perform LF normalization +# Set the default behavior, in case people don't have core.autocrlf set. * text=auto -# Custom for Visual Studio -*.cs diff=csharp -*.sln merge=union -*.csproj merge=union -*.vbproj merge=union -*.fsproj merge=union -*.dbproj merge=union - -# Standard to msysgit -*.doc diff=astextplain -*.DOC diff=astextplain -*.docx diff=astextplain -*.DOCX diff=astextplain -*.dot diff=astextplain -*.DOT diff=astextplain -*.pdf diff=astextplain -*.PDF diff=astextplain -*.rtf diff=astextplain -*.RTF diff=astextplain - -# doxygen generated files -docs/html/ -docs/xml/ \ No newline at end of file +# Explicitly declare text files you want to always be normalized and converted +# to native line endings on checkout. +*.py text eol=lf +*.rst text eol=lf +*.sh text eol=lf +*.h text eol=lf +*.cpp text eol=lf +*.c text eol=lf +.yaml text eol=lf +*.yml text eol=lf +*.md text eol=lf +*.txt text eol=lf +*.json text eol=lf +*.properties text eol=lf +LICENSE text eol=lf +nurfile text eol=lf +.gitignore text eol=lf +.gitattributes text eol=lf +.clang-format text eol=lf +.clang-tidy text eol=lf +Makefile text eol=lf +*.svg text eol=lf +*.ino text eol=lf +*.dot text eol=lf +*.cmake text eol=lf +*.css text eol=lf +Doxyfile text eol=lf diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 1366655..ae4c6c8 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -1,16 +1,32 @@ -name: DoxyGen build +name: Docs on: pull_request: - branches: - - master + branches: [master] push: - branches: - - master + branches: [master] + tags: ["*"] + workflow_dispatch: + +permissions: {} + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/master' }} jobs: - build-docs: - uses: nRF24/.github/.github/workflows/build_docs.yaml@main + build: + uses: nRF24/.github/.github/workflows/build_docs.yaml@review-ci with: - deploy-gh-pages: ${{ github.event_name == 'push' }} # happens only on master branch + doxygen-version: "1.15.0" + + deploy: + needs: [build] + if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/') + permissions: + # to authenticate the gh-pages environment + id-token: write + # to upload to GitHub Pages + pages: write + uses: nRF24/.github/.github/workflows/deploy_docs.yaml@review-ci secrets: inherit diff --git a/README.md b/README.md index e45fa09..bee2547 100644 --- a/README.md +++ b/README.md @@ -5,5 +5,3 @@ See the [documentation section](http://nRF24.github.io/RF24Audio) for more info. Only AVR devices are supported. For ESP32 and Arduino Due, see [AutoAnalogAudio](https://github.com/TMRh20/AutoAnalogAudio), a more versatile audio input/output library. - - diff --git a/RF24Audio.h b/RF24Audio.h index 31d7538..af5ca8f 100644 --- a/RF24Audio.h +++ b/RF24Audio.h @@ -106,7 +106,7 @@ class RF24Audio * Get any of the preset radio addresses * * Useful for listening nodes who wish to create private or additional radio groups - * The library has 14 predefined radio addreses. All radios listen/write on the first + * The library has 14 predefined radio addresses. All radios listen/write on the first * two addresses (0, 1), and engage a private channel based on the radio number. * Radio 0 listens on address 2, Radio 1 on address 3, etc. * @@ -172,18 +172,3 @@ void RX(); * This sketch is demonstrates how to interact with the audio library directly using the core * RF24 radio library: http://nRF24.github.io/RF24/ */ - -/** - * @page Setup Boards & Wiring - * @section Board Wiring - * This page displays different options for wiring/board configuration. - * - * @image html "images/NRF1.jpg" height=25% width=25% - * - * Wiring diagram for DIY module connector. May not be needed depending on module: - * @image html "images/RF24AudioBasic_LargeAntenna.jpg" height=45% width=45% - * @image html "images/NRF2.jpg" height=20% width=20% - * @image html "images/RF24AudioBasic_SmallAntenna.jpg" height=45% width=45% - * Wiring diagram for SD streaming/multicast using TMRpcm library: - * @image html "images/RF24Audio_FullSD.jpg" height=65% width=65% - */ \ No newline at end of file diff --git a/docs/Doxyfile b/docs/Doxyfile index cae857a..fab8fc8 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -17,6 +17,8 @@ # Project related configuration options #--------------------------------------------------------------------------- +PROJECT_ICON = images/favicon.ico + # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by # double-quotes, unless you are using Doxywizard) that should identify the # project for which the documentation is generated. This name is used in the @@ -165,7 +167,7 @@ EXAMPLE_RECURSIVE = YES # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = ../images +IMAGE_PATH = ./images/ # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that # is part of the input, its contents will be placed on the main page @@ -174,6 +176,12 @@ IMAGE_PATH = ../images USE_MDFILE_AS_MAINPAGE = main_page.md +# Don't display the ugly/complicated "tree view" side menu. +# And, restore the top (simpler) navigation bar. +# As of doxygen v1.13.0, these default values changed from NO to YES +GENERATE_TREEVIEW = NO +DISABLE_INDEX = NO + #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- @@ -232,6 +240,35 @@ HTML_EXTRA_STYLESHEET = doxygen-custom.css HTML_COLORSTYLE = TOGGLE +# If the TIMESTAMP tag is set different from NO then each generated page will contain +# the date or date and time when the page was generated. Setting this to NO can help +# when comparing the output of multiple runs. +# +# Possible values are: YES, NO, DATETIME and DATE. +# +# The default value is: NO. + +TIMESTAMP = DATE + +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = NO + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = YES + #--------------------------------------------------------------------------- # Configuration options related to the LaTeX output #--------------------------------------------------------------------------- diff --git a/docs/doxygen-custom.css b/docs/doxygen-custom.css index 7d56191..4a3c469 100644 --- a/docs/doxygen-custom.css +++ b/docs/doxygen-custom.css @@ -1,3 +1,166 @@ table.markdownTable th { color: unset; } + +/* overrides from default CSS for some admonitions */ +dl.note, +dl.remark, +dl.warning, +dl.attention, +dl.important, +dl.deprecated, +dl.see { + color: unset; + box-shadow: 5px 5px 5px hsla(0, 0%, 19.2%, 0.5); +} + +dl.remark { + background: var(--remark-color-bg); + border-left: 8px solid var(--remark-color-hl); +} + +dl.remark dt { + color: var(--remark-color-hl); +} + +dl.important dt { + color: var(--important-color-hl); +} + +dl.important { + background: var(--important-color-bg); + border-left: 8px solid var(--important-color-hl); +} + +dl.attention dt { + color: var(--attention-color-hl); +} + +dl.attention { + background: var(--attention-color-bg); + border-left: 8px solid var(--attention-color-hl); +} + +dl.deprecated dt { + color: var(--deprecated-color-hl); +} + +dl.deprecated { + background: var(--deprecated-color-bg); + border-left: 8px solid var(--deprecated-color-hl); +} + +/* special rules to accent `/see` or `/sa` command output */ +dl.see { + background: var(--seealso-color-bg); + border-left: 8px solid var(--seealso-color-hl); +} + +dl.see dt { + color: var(--seealso-color-hl); +} + +dl.see { + padding: 10px; + margin: 10px 0px; + overflow: hidden; + margin-left: 0; + border-radius: 4px; +} + +dl.see dd { + margin-left: 0; +} + +/* admonition icons */ +dl.note dt::before { + background-color: var(--note-color-hl); + mask-image: var(--note-icon); +} + +dl.see dt::before { + background-color: var(--seealso-color-hl); + mask-image: var(--seealso-icon); +} + +dl.remark dt::before { + background-color: var(--remark-color-hl); + mask-image: var(--remark-icon); +} + +dl.warning dt::before { + background-color: var(--warning-color-hl); + mask-image: var(--warning-icon); +} + +dl.deprecated dt::before { + background-color: var(--deprecated-color-hl); + mask-image: var(--deprecated-icon); +} + +dl.important dt::before { + background-color: var(--important-color-hl); + mask-image: var(--important-icon); +} + +dl.attention dt::before { + background-color: var(--attention-color-hl); + mask-image: var(--attention-icon); +} + +dl.note dt::before, +dl.see dt::before, +dl.warning dt::before, +dl.remark dt::before, +dl.deprecated dt::before, +dl.important dt::before, +dl.attention dt::before { + vertical-align: middle; + background-repeat: no-repeat; + content: ""; + display: inline-block; + height: 2em; + width: 2em; + margin-right: 0.25rem; +} + +dl.note dt, +dl.see dt, +dl.warning dt, +dl.remark dt, +dl.deprecated dt, +dl.important dt, +dl.attention dt { + margin-top: -0.35em; + margin-bottom: 0.5em; +} + +/* icon SVG data */ +*:root { + --note-icon: url('data:image/svg+xml;utf8,'); + --warning-icon: url('data:image/svg+xml;utf8,'); + --remark-icon: url('data:image/svg+xml;utf8,'); + --attention-icon: url('data:image/svg+xml;utf8,'); + --important-icon: url('data:image/svg+xml;utf8,'); + --seealso-icon: url('data:image/svg+xml;utf8,'); + --deprecated-icon: url('data:image/svg+xml;utf8,'); +} + +/* color overrides */ +html, +html.dark-mode { + --note-color-hl: hsl(213.7, 92.8%, 62%); + --note-color-bg: hsla(213.7, 92.8%, 62%, 12.5%); + --warning-color-hl: hsl(40.6, 72.1%, 47.8%); + --warning-color-bg: hsla(40.6, 72.1%, 47.8%, 12.5%); + --attention-color-hl: hsl(2.7, 92.6%, 62.9%); + --attention-color-bg: hsla(2.7, 92.6%, 62.9%, 12.5%); + --deprecated-color-hl: hsl(0, 0%, 47%); + --deprecated-color-bg: hsla(0, 0%, 47%, 12.5%); + --seealso-color-hl: hsl(323, 72%, 52%); + --seealso-color-bg: hsla(323, 72%, 52%, 12.5%); + --remark-color-hl: hsl(128.4, 49.2%, 48.6%); + --remark-color-bg: hsla(128.4, 49.2%, 48.6%, 12.5%); + --important-color-hl: hsl(262.4, 89.8%, 73.1%); + --important-color-bg: hsla(262.4, 89.8%, 73.1%, 12.5%); +} \ No newline at end of file diff --git a/images/NRF1.jpg b/docs/images/NRF1.jpg similarity index 100% rename from images/NRF1.jpg rename to docs/images/NRF1.jpg diff --git a/images/NRF2.jpg b/docs/images/NRF2.jpg similarity index 100% rename from images/NRF2.jpg rename to docs/images/NRF2.jpg diff --git a/images/RF24AudioBasic_LargeAntenna.jpg b/docs/images/RF24AudioBasic_LargeAntenna.jpg similarity index 100% rename from images/RF24AudioBasic_LargeAntenna.jpg rename to docs/images/RF24AudioBasic_LargeAntenna.jpg diff --git a/images/RF24AudioBasic_SmallAntenna.jpg b/docs/images/RF24AudioBasic_SmallAntenna.jpg similarity index 100% rename from images/RF24AudioBasic_SmallAntenna.jpg rename to docs/images/RF24AudioBasic_SmallAntenna.jpg diff --git a/images/RF24Audio_FullSD.jpg b/docs/images/RF24Audio_FullSD.jpg similarity index 100% rename from images/RF24Audio_FullSD.jpg rename to docs/images/RF24Audio_FullSD.jpg diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..c15a1650af557d6ec815ebd7c0b5dbf5cc080676 GIT binary patch literal 4286 zcmc(iTT@%t8HTmbTLO|^B{RuQF8dF1+sS`u|3GnV5NCurSYW$$;sBD+2}$S-;$VR> z*!ajn#&(=Z-R9)9?o6jMz3hMR?3p+3S{oE}NPB1FS+=ab*Lv3Xt?zxmg~y}t&nKUF z#NVEqzwvlJ@OV7G<=|JI-*JfVf9*%_oqePG=NxOG=-7*E4&Qs5*y0{Sc65_ zxlNG&Hiskmy>qbo^6(~C-zHnIT>f|pwm%O$@s9XCv#@)!u;VN5EPkUm0$=F}T^rw^ ztNIsoZoNdu_Fv(<{|df4-@&){J-iQofcMdlu=iiVKKcpP@jqZae+~1+KVf~%!O!A5 z@ytGW<-WVeIh-rj=-By|YyM5H-Bo=lSZ@9qKkEQ`ZwR`70s5r^^noa}p%}E`IJD6O zw6P@AiyYU=P^VH*gJ~!;87Nmct}Q{ip5@57|DQ?A=kmRYMLACka1F7}bP?KMOs=o@ zM;+=_PX@TIokOW%Sw zvkmXkHtg(e>T(BmVHb9B7gqTWtd+a4Dtj>3?!nyPsNRRU^}rqC^G%NRd$3mdPLc15 zIVH{)Yvj3B?l#xv$ZR{pdzb@w&o9CE4(d;vNQ)ehpM^JGdF%DB`R85!g*N;TKZNI_ zkN)@g_+xlfwQ=A7Z_ep+`j6H(?=T0jdvXo&E1!Of_iO*6MqZ+mTItxL79YQcZ@#%bpF{=GSp2O#yGWf zeG{tOLlpYlohJS?w5=EPfkpDk{E|AIt3r$3fp%q?{20{HD6H_~6Mo3iE-t$Lr-}bw z_9^`+Og~tHcc%tBwGK0}0c-s(%=n&MOaF2gdh~4kA#YnIhK68uM8{R#LpfxpY+Dh z+wj+(F@EwlUo`T=cxif5P|rOD%lw68WPs7}svM z#ILWCe}(+DC$0R%BbT2zkms)sh9%z|DuMT}Mt+*}d&2PcH1W@M!^>yd2>DmHTlp(b zpNB>59b*6g9nA0mG+#9l*2tQ|iD?}cJx{DPl4;a_gUFCRu zWD*AX+T^sOlFuB#94*WGKE3~)p1*M+1mAh`WBGb+RPud`HTppm=FF{@_>JNd>Ym!; zeWJPkv<&NSiu}xx8~-r*!K~D_&{qSWXDs=DDzx&GNAxA~gVa`2{Tq4mZ?IPv4qN%z z1E`l4VPtDAe2Ja_E zj$T0jQ)jY{Ivjy#wjQqg`n3Lou8uf21kx#$XmfG-(hw^NU!U=zr z@sE%{u|obvL;kyj|I&Ya=jaX1@kdYi4MCCGTBh4PRd*G;oA7EbCm-WjP*UV5e){wX-s{!`du_%ma8@`Btwsg{)*Btd)N$i0=nYm#ds>5Oa%ew~qyEe{! z_VI2q%(F?A>v2dH{UK;m8F@bt9!f8B=ZhX6Ab+6^zarvKLJ7v9d{JLbCpQx%!9SJ6*+RygSpod4H6581`|My-fOPFvIm? ij#+u`=)qupp7^Zoy>yf-DMy)(JIbZl8`j1<{rMRY83?oh literal 0 HcmV?d00001 diff --git a/docs/main_page.md b/docs/main_page.md index 42088f2..d4c33bf 100644 --- a/docs/main_page.md +++ b/docs/main_page.md @@ -6,18 +6,20 @@ This class implements a realtime audio streaming solution using nRF24L01(+) radi by the newly [optimized RF24 library fork](http://nRF24.github.com/RF24/). ## Features -- User friendly setup and configuration: For beginners too: Just connect a radio module, microphone, and speaker. The library handles the rest. -- Recording and broadcasting of audio to multiple devices using only Arduino, RF24 modules and input/output (speaker/microphone) devices -- Multicast: Enables broadcasting to all nodes, single nodes, or partial groups of nodes -- External controls: Use external buttons or code to control audio streaming -- Volume control: Use external buttons or code to control audio volume on receiving devices. -- Remote control: Start recording remotely via radio commands (Currently cannot stop remote recording) -- LED Indicator/Visualization: Indicates audio playback and amplitude. -- Customization: Using the underlying RF24 core library allows custom interaction with audio devices running this library. Receive audio data + +- **User friendly setup and configuration:** For beginners too: Just connect a radio module, microphone, and speaker. The library handles the rest. +- **Recording and broadcasting of audio** to multiple devices using only Arduino, RF24 modules and input/output (speaker/microphone) devices +- **Multicast:** Enables broadcasting to all nodes, single nodes, or partial groups of nodes +- **External controls:** Use external buttons or code to control audio streaming +- **Volume control:** Use external buttons or code to control audio volume on receiving devices. +- **Remote control:** Start recording remotely via radio commands (Currently cannot stop remote recording) +- **LED Indicator/Visualization:** Indicates audio playback and amplitude. +- **Customization:** Using the underlying RF24 core library allows custom interaction with audio devices running this library. Receive audio data and stream it to a PC over USB, create and broadcast computer generated audio in realtime, and more! See the [USB_Audio example](USB_Audio_8ino-example.html) for more info. -- Create additional node groups: Allows nodes to join private broadcast groups, and multicast only within their group as desired. See advanced section below. +- **Create additional node groups:** Allows nodes to join private broadcast groups, and multicast only within their group as desired. See advanced section below. ## How to learn more + - [RF24Audio Library Class Documentation](classRF24Audio.html) - [RF24: Underlying radio driver (2014 - Newly Optimized)](http://nRF24.github.io/RF24/) - [My Blog: RF24 Optimization Overview](http://tmrh20.blogspot.com/2014/03/high-speed-data-transfers-and-wireless.html) @@ -27,6 +29,7 @@ by the newly [optimized RF24 library fork](http://nRF24.github.com/RF24/). - [Newly Optimized RF24Network Class](http://nRF24.github.io/RF24Network/) ## Configuration and Setup + The settings for the library will generally be detected automatically. To change from the default pin assignments etc, edit the userConfig.h file. The mandatory user options in the configuration file are shown below: @@ -37,20 +40,22 @@ userConfig.h file. The mandatory user options in the configuration file are show ``` ### Pin Assignments -@see [the Setup page](Setup.html) for wiring diagrams -- Speakers: Arduino Uno,Nano,etc: pins 9, 10 Arduino Mega: 11, 12 (Timer pins cannot be changed, but can use 1 pin and ground) -- pin A0: Microphone/Input pin -- pin A1: Transmission/Recording Start pin -- pin A2: Volume Up -- pin A3: Volume Down -- pin A4: Trigger remote recording (Only working with dual devices) -- Cannot be changed: LED Pin: Uno,Nano,etc: pin 6 Mega 2560: pin 13 (main LED pin) +@see [the Setup page](setup.md) for wiring diagrams -See http://arduino.cc/en/Tutorial/InputPullupSerial for info on how to wire the buttons to the pins +- **Speakers:** Arduino Uno,Nano,etc: pins 9, 10 Arduino Mega: 11, 12 (Timer pins cannot be changed, but can use 1 pin and ground) +- **pin A0:** Microphone/Input pin +- **pin A1:** Transmission/Recording Start pin +- **pin A2:** Volume Up +- **pin A3:** Volume Down +- **pin A4:** Trigger remote recording (Only working with dual devices) +- **Cannot be changed:** LED Pin: Uno,Nano,etc: pin 6 Mega 2560: pin 13 (main LED pin) + +See for info on how to wire the buttons to the pins See userConfig.h to change default pin assignments and options. ## Advanced Usage + The radio pipes are defined as follows. For more complex multicast scenarios, radios can listen on any combination of pipes.
Use the getAddress(); function to access the address array. @@ -70,8 +75,15 @@ const uint64_t pipes[14] = {0xABCDABCD71LL, 0x544d52685FLL, 0x544d526869LL}; ``` -By default, all radios will open the same reading & writing pipes on the first two addresses.
-Any radio that wishes to transmit, will reverse the addresses on the first two pipes, and begin to transmit to all the other nodes.
-Every radio will automatically be assigned the first two addresses, then one of the remaining addresses as a private channel, based on its radio number:
(0 = pipes[2], 1 = pipes[3])
+ +By default, all radios will open the same reading & writing pipes on the first two addresses. + +Any radio that wishes to transmit, will reverse the addresses on the first two pipes, and begin to transmit to all the other nodes. + +Every radio will automatically be assigned the first two addresses, then one of the remaining addresses as a private channel, based on its radio number: + +```text +(0 = pipes[2], 1 = pipes[3]) +``` Additional addresses can be added by modifying the address array listed in userConfig.h diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..e8b6faf --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,19 @@ +# Setup Boards & Wiring + +## Board Wiring + +This page displays different options for wiring/board configuration. + +![images/NRF1.jpg](images/NRF1.jpg){height=25% width=25%} + +Wiring diagram for DIY module connector. May not be needed depending on module: + +![images/RF24AudioBasic_LargeAntenna.jpg](images/RF24AudioBasic_LargeAntenna.jpg){height=45% width=45%} + +![images/NRF2.jpg](images/NRF2.jpg){height=20% width=20%} + +![images/RF24AudioBasic_SmallAntenna.jpg](images/RF24AudioBasic_SmallAntenna.jpg){height=45% width=45%} + +Wiring diagram for SD streaming/multicast using TMRpcm library: + +![images/RF24Audio_FullSD.jpg](images/RF24Audio_FullSD.jpg){height=65% width=65%} From 2674894d016e8965a8bac170641a71992ea39e9b Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Tue, 25 Nov 2025 05:50:03 -0800 Subject: [PATCH 2/3] enable RTD builds for PRs --- .github/doxygen.py | 32 ++++++++++++++++++++++++++++++++ .readthedocs.yaml | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 .github/doxygen.py create mode 100644 .readthedocs.yaml diff --git a/.github/doxygen.py b/.github/doxygen.py new file mode 100644 index 0000000..ddd84f8 --- /dev/null +++ b/.github/doxygen.py @@ -0,0 +1,32 @@ +"""WARNING -- FOR CI ONLY + +This script is meant to be execute in CI only. +Running this locally will alter the Doxyfile. +Such changes SHOULD NOT be pushed to the remote. +""" + +from pathlib import Path + +DOCS_DIR = Path(__file__).parent.parent / "docs" +PROPERTIES = DOCS_DIR.parent / "library.properties" +CONFIG = DOCS_DIR / "Doxyfile" +TMP = DOCS_DIR / "doxygenAction" + + +def overwrite_doxygen_value(): + properties = PROPERTIES.read_text(encoding="utf-8").splitlines() + for line in properties: + if line.startswith("version="): + _, value = line.split("=", 1) + version = value.strip() + break + else: + raise RuntimeError("version not found in library.properties") + config = CONFIG.read_text(encoding="utf-8") + TMP.write_text(f"PROJECT_NUMBER = {version}\n", encoding="utf-8") + config += f"\n@INCLUDE = {str(TMP)}\n" + CONFIG.write_text(config, encoding="utf-8") + + +if __name__ == "__main__": + overwrite_doxygen_value() diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..e467b11 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +build: + os: "ubuntu-24.04" + # apt_packages: + # - libclang1-12 + # - libclang-cpp12 + tools: + python: "3" + commands: + # Install doxygen from source distributions (conda forge does not keep up-to-date doxygen releases) + - > + DOXYGEN_VERSION="1.15.0" && + RELEASE_TITLE=$(echo ${DOXYGEN_VERSION} | tr '.' '_') && + mkdir .doxygen && cd .doxygen && + curl -L "https://github.com/doxygen/doxygen/releases/download/Release_${RELEASE_TITLE}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz" --output doxygen.tar.gz && + gunzip doxygen.tar.gz && + tar xf doxygen.tar && + mv doxygen-${DOXYGEN_VERSION}/bin/doxygen ./ + # get lib version & overwrite Doxyfile values + - python3 .github/doxygen.py + # run doxygen + - cd docs && ../.doxygen/doxygen + # copy output to RTD output path for HTML files + - ls -R docs/html/ + - mkdir -p ${READTHEDOCS_OUTPUT} + - mv docs/html/ "${READTHEDOCS_OUTPUT}" From 86fbc1978e2c709fb812a5e7f9e47ae97300b332 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Thu, 27 Nov 2025 02:08:41 -0800 Subject: [PATCH 3/3] switch CI back to org-repo main branch --- .github/workflows/doxygen.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index ae4c6c8..9fcd4d1 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -16,7 +16,7 @@ concurrency: jobs: build: - uses: nRF24/.github/.github/workflows/build_docs.yaml@review-ci + uses: nRF24/.github/.github/workflows/build_docs.yaml@main with: doxygen-version: "1.15.0" @@ -28,5 +28,5 @@ jobs: id-token: write # to upload to GitHub Pages pages: write - uses: nRF24/.github/.github/workflows/deploy_docs.yaml@review-ci + uses: nRF24/.github/.github/workflows/deploy_docs.yaml@main secrets: inherit