remove docs/sphinx folder and update RTD config

nRF24 · Sep 24, 2024 · 5551fdf · 5551fdf
1 parent 63cadc4
commit 5551fdf
Show file tree

Hide file tree

Showing 69 changed files with 55 additions and 988 deletions.
diff --git a/.gitignore b/.gitignore
@@ -40,6 +40,7 @@ __pycache__/
 *.pyc
 *.egg*
 build/
+_build/
 *CMakeUserPresets*.json
 *.tar.gz
 

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -6,15 +6,37 @@
 version: 2
 
 build:
-  os: "ubuntu-20.04"
+  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.12.0" &&
+      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 docs/ci.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}"
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/sphinx/conf.py
+# # Build documentation in the docs/ directory with Sphinx
+# sphinx:
+#   configuration: docs/sphinx/conf.py
 
-# install Python requirements required to build docs
-python:
-  install:
-    - requirements: docs/sphinx/requirements.txt
+# # install Python requirements required to build docs
+# python:
+#   install:
+#     - requirements: docs/sphinx/requirements.txt
diff --git a/cspell.config.yaml b/cspell.config.yaml
@@ -78,6 +78,7 @@ words:
   - DIRSET
   - Disabl
   - Doherty
+  - Doxyfile
   - doxygen
   - doxygenfile
   - doxygenfunction

diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -15,7 +15,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 
-PROJECT_ICON = sphinx/_static/new_favicon.ico
+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
@@ -372,24 +372,6 @@ HTML_DYNAMIC_SECTIONS  = YES
 
 GENERATE_LATEX         = NO
 
-#---------------------------------------------------------------------------
-# Configuration options related to the XML output
-#---------------------------------------------------------------------------
-
-# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that
-# captures the structure of the code including all documentation.
-# The default value is: NO.
-
-GENERATE_XML           = YES
-
-# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
-# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
-# it.
-# The default directory is: xml.
-# This tag requires that the tag GENERATE_XML is set to YES.
-
-XML_OUTPUT             = sphinx/xml
-
 #---------------------------------------------------------------------------
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------

diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,4 @@
-# Please browse the docs from either http://nrf24.github.io/RF24 or https://rf24.rtfd.io
+# Please browse the docs from either http://nrf24.github.io/RF24
 
 ## Intended for use in Doxygen
 
@@ -14,26 +14,10 @@ Navigate to the repo's docs folder:
 cd docs
 ```
 
-Install Doxygen (v1.9.5 or newer) and run the following command from the repo's docs folder:
+Install Doxygen (v1.12.0 or newer) and run the following command from the repo's docs folder:
 
 ```shell
 doxygen
 ```
 
-The Doxygen HTML output is now in docs/html. The Doxygen XML output in docs/sphinx/xml can be optionally used to generate Sphinx output.
-
-### Generating Sphinx docs (optional)
-
-To build the Sphinx docs based on Doxygen's XML output, first install the necessary python dependencies.
-
-``` shell
-python -m pip install docs/sphinx/requirements.txt
-```
-
-Now build the Sphinx docs (after building the Doxygen output) from the repo's docs folder:
-
-```shell
-sphinx-build sphinx _build/html
-```
-
-The Sphinx HTML output now exists in docs/_build/html.
+The Doxygen HTML output is now in docs/html.
diff --git a/docs/ci.py b/docs/ci.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import json
+
+DOCS_DIR = Path(__file__).parent
+PROPERTIES = DOCS_DIR.parent / "library.json"
+CONFIG = DOCS_DIR / "Doxyfile"
+TMP = DOCS_DIR / "doxygenAction"
+
+
+def overwrite_doxygen_value():
+    properties = json.loads(PROPERTIES.read_text(encoding="utf-8"))
+    assert "version" in properties
+    config = CONFIG.read_text(encoding="utf-8")
+    TMP.write_text("PROJECT_NUMBER = {}\n".format(properties["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 --git a/docs/sphinx/_static/Logo large.png → docs/images/Logo large.png b/docs/sphinx/_static/Logo large.png → docs/images/Logo large.png
diff --git a/docs/sphinx/_static/new_favicon.ico → docs/images/favicon.ico b/docs/sphinx/_static/new_favicon.ico → docs/images/favicon.ico
diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile
diff --git a/docs/sphinx/README.md b/docs/sphinx/README.md
diff --git a/docs/sphinx/RF24_config_8h.rst b/docs/sphinx/RF24_config_8h.rst
diff --git a/docs/sphinx/_static/custom_material.css b/docs/sphinx/_static/custom_material.css
diff --git a/docs/sphinx/classRF24.rst b/docs/sphinx/classRF24.rst