[Feature] Conditional Documentation and CMake instead of Submodule for Doxygen-Is-Awesome

.github/workflows/deploy-docs.yml

@@ -3,45 +3,60 @@ name: Docs
 # Controls when the action will run. Triggers the workflow on push or pull request
 # events but only for the master branch
 on:
-  push:
-    branches: ["main"] 
-  workflow_dispatch:
-  
+    push:
+        branches: ["main"]
+    workflow_dispatch:
+
 jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          submodules: "true"
-
-      - name: Install dependencies
-        run: sudo apt-get update && sudo apt-get install -y wget graphviz rsync
-        shell: bash
-
-      - name: Install Doxygen v1.9.6
-        run: |
-          transformed_version=$(echo "1.9.6" | tr '.' '_')
-          wget https://github.com/doxygen/doxygen/releases/download/Release_${transformed_version}/doxygen-1.9.6.linux.bin.tar.gz
-          tar -xzf doxygen-1.9.6.linux.bin.tar.gz
-          sudo mv doxygen-1.9.6/bin/doxygen /usr/local/bin/doxygen
-        shell: bash
-
-      - name: Generate Doxygen Documentation
-        run: doxygen Doxyfile
-        shell: bash
-
-      - name: Create .nojekyll (ensures pages with underscores work on gh pages)
-        run: touch docs/doxygen/html/.nojekyll
-        shell: bash
-
-      - name: Deploy to GitHub Pages
-        uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          repository-name: SyndemicsLab/respond
-          branch: gh-pages
-          folder: docs/doxygen/html
-          target-folder: ./
-          ssh-key: ${{ secrets.RESPOND_DOCS_DEPLOY_SSH_PRIVATE }}
-          token: ${{ secrets.OAUTH_TOKEN }}
+    deploy:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8
+              with:
+                  submodules: "true"
+
+            - name: Install dependencies
+              run: sudo apt-get update && sudo apt-get install -y wget graphviz rsync
+              shell: bash
+
+            - name: Install Doxygen v1.9.6
+              run: |
+                  transformed_version=$(echo "1.9.6" | tr '.' '_')
+                  wget https://github.com/doxygen/doxygen/releases/download/Release_${transformed_version}/doxygen-1.9.6.linux.bin.tar.gz
+                  tar -xzf doxygen-1.9.6.linux.bin.tar.gz
+                  sudo mv doxygen-1.9.6/bin/doxygen /usr/local/bin/doxygen
+              shell: bash
+
+            - name: Install Eigen3
+              uses: kupns-aka-kupa/setup-eigen3@master
+              id: install-eigen3
+              with:
+                  version: 3.4.0
+              env:
+                  CMAKE_GENERATOR: Ninja
+
+            - name: Configure Project
+              env:
+                  EIGEN3_INCLUDE_DIR: ${{ steps.install-eigen3.outputs.EIGEN3_INCLUDE_DIR }}
+                  EIGEN3_DIR: ${{ steps.install-eigen3.outputs.EIGEN3_DIR}}
+              run: >
+                  cmake --config --preset release-linux-shared-config
+
+            - name: Generate Doxygen Documentation
+              run: doxygen Doxyfile
+              shell: bash
+
+            - name: Create .nojekyll (ensures pages with underscores work on gh pages)
+              run: touch docs/doxygen/html/.nojekyll
+              shell: bash
+
+            - name: Deploy to GitHub Pages
+              uses: JamesIves/github-pages-deploy-action@v4
+              with:
+                  repository-name: SyndemicsLab/respond
+                  branch: gh-pages
+                  folder: docs/doxygen/html
+                  target-folder: ./
+                  ssh-key: ${{ secrets.RESPOND_DOCS_DEPLOY_SSH_PRIVATE }}
+                  token: ${{ secrets.OAUTH_TOKEN }}

.gitignore

@@ -1,3 +1,8 @@
+# Doxyfile generated by CMake Configuration
+# Because we include doxygen-is-awesome we need to render the Doxygen file each time CMake is run. Thus, the base Doxyfile must become a generated file during CMake configuration.
+# To modify the Doxyfile, edit docs/Doxyfile.in and re-run CMake. It will build the new Doxyfile at the root of the build tree.
+Doxyfile
+
 .metadata
 bin/
 tmp/

CMakePresets.json

@@ -56,6 +56,7 @@
                 "CMAKE_BUILD_TYPE": "Release",
                 "RESPOND_BUILD_TESTS": "OFF",
                 "RESPOND_INSTALL": "ON",
+                "RESPOND_BUILD_DOCS": "ON",
                 "RESPOND_CALCULATE_COVERAGE": "OFF"
             }
         },

Doxyfile → Doxyfile.in

@@ -1377,9 +1377,9 @@ HTML_STYLESHEET        =
 # documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = docs/doxygen-awesome-css/doxygen-awesome.css \
-                        docs/doxygen-awesome-css/doxygen-awesome-sidebar-only.css \
-                        docs/doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.css \
+HTML_EXTRA_STYLESHEET  = @AWESOME_CSS_DIR@/doxygen-awesome.css \
+                        @AWESOME_CSS_DIR@/doxygen-awesome-sidebar-only.css \
+                        @AWESOME_CSS_DIR@/doxygen-awesome-sidebar-only-darkmode-toggle.css \
                         docs/src/custom.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
@@ -1390,8 +1390,8 @@ HTML_EXTRA_STYLESHEET  = docs/doxygen-awesome-css/doxygen-awesome.css \
 # files will be copied as-is; there are no commands or markers available.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_FILES       = docs/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \
-                            docs/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js \
+HTML_EXTRA_FILES       = @AWESOME_CSS_DIR@/doxygen-awesome-darkmode-toggle.js \
+                            @AWESOME_CSS_DIR@/doxygen-awesome-fragment-copy-button.js \
                             docs/images/png/favicon.png
 
 # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output

cmake/BuildBinaries.cmake

@@ -11,4 +11,9 @@ endif()
 if(RESPOND_BUILD_BENCH OR RESPOND_BUILD_ALL)
     message(STATUS "Generating benchmarks")
     add_subdirectory(extras/benchmarking)
+endif()
+
+if(RESPOND_BUILD_DOCS OR RESPOND_BUILD_ALL)
+    message(STATUS "Generating documentation")
+    include(${PRIVATE_MODULE_PATH}/LoadDoxygenIsAwesome.cmake)
 endif()

cmake/LoadDoxygenIsAwesome.cmake

@@ -0,0 +1,19 @@
+
+message(CHECK_START "Fetching DoxygenIsAwesome...")
+list(APPEND CMAKE_MESSAGE_INDENT "  ")
+include(FetchContent)
+
+FetchContent_Declare(
+    doxygen-awesome-css
+    URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/heads/main.zip
+)
+FetchContent_MakeAvailable(doxygen-awesome-css)
+
+# Save the location the files were cloned into
+# This allows us to get the path to doxygen-awesome.css
+FetchContent_GetProperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR)
+
+# Generate the Doxyfile
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile)
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

cmake/options.cmake

@@ -6,6 +6,9 @@ option(RESPOND_BUILD_PIC "Build position independent code (-fPIC)" OFF)
 # build shared libraries
 option(BUILD_SHARED_LIBS "Build shared libraries instead of static libraries" ON)
 
+# build documentation
+option(RESPOND_BUILD_DOCS "Build Documentation" ON)
+
 # testing options
 option(RESPOND_BUILD_TESTS "Build tests" OFF)