enable docs preview in PRs (#43)

Relates to nRF24/RF24#1003 but Sphinx-related changes are not applicable here.

Author: 2bndy5

Diff for: .github/doxygen.py

@@ -0,0 +1,28 @@
+"""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
+import subprocess
+
+DOCS_DIR = Path(__file__).parent.parent / "docs"
+CONFIG = DOCS_DIR / "Doxyfile"
+TMP = DOCS_DIR / "doxygenAction"
+
+
+def overwrite_doxygen_value():
+    result = subprocess.run(
+        ["git", "describe", "--tags"], check=True, capture_output=True
+    )
+    version = result.stdout.decode(encoding="utf-8").strip().lstrip("v")
+    config = CONFIG.read_text(encoding="utf-8")
+    TMP.write_text("PROJECT_NUMBER = {}\n".format(version), encoding="utf-8")
+    config += f"\n@INCLUDE = {str(TMP)}\n"
+    CONFIG.write_text(config, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    overwrite_doxygen_value()

Diff for: .github/workflows/doxygen.yml

@@ -30,4 +30,5 @@ jobs:
     uses: nRF24/.github/.github/workflows/build_docs.yaml@main
     with:
       deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }}
+      doxygen-version: '1.13.2'
     secrets: inherit

Diff for: .gitignore

@@ -5,6 +5,7 @@
 # ignore docs folder
 docs/html/
 docs/xml/
+docs/doxygenAction
 
 # ignore CMake stuff
 build/

Diff for: .readthedocs.yaml

@@ -0,0 +1,33 @@
+# .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-22.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.13.2" &&
+      mkdir .doxygen && cd .doxygen &&
+      echo $(pwd) &&
+      echo "https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz" &&
+      curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > 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}"

Diff for: docs/Doxyfile

@@ -156,6 +156,12 @@ SHOW_FILES             = NO
 
 SHOW_NAMESPACES        = NO
 
+# 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 the input files
 #---------------------------------------------------------------------------