docs: revise CI (#51)

corresponds to nRF24/.github#23

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.

* enable RTD builds for PRs

Author: 2bndy5

.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/
+# 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

.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()

.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:
+  build:
     uses: nRF24/.github/.github/workflows/build_docs.yaml@main
     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@main
     secrets: inherit

.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}"

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.
-
-

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%
- */

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
 #---------------------------------------------------------------------------