Generate Doxyfile via CMake and only fetch doc dependencies if required.

.github/workflows/doxygen-check.yml

@@ -10,11 +10,15 @@ jobs:
   doxygen-check:
     name: Doxygen Check
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    container:
+      image: "ghcr.io/kamping-site/kamping-ci:2024.2"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3.0.2
         with:
           submodules: 'recursive'
-      - uses: mattnotmitt/doxygen-action@v1.9.4
-        with:
-          doxyfile-path: 'docs/Doxyfile'
+      - name: version
+        run: doxygen --version
+      - name: cmake
+        run: cmake -B build
+      - name: run-doxygen
+        run: cmake --build build/ --target docs          

.github/workflows/doxygen-deployment.yml

@@ -4,30 +4,29 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
 
 jobs:
   build-documentation:
     runs-on: ubuntu-latest
+    container:
+      image: "ghcr.io/kamping-site/kamping-ci:2024.2"
 
     steps:
     - uses: actions/checkout@v3
       with:
           submodules: true
-
+    - name: Configure project
+      run: cmake -B build
     # Build the HTML documentation
-    - name: Doxygen Action
-      uses: mattnotmitt/doxygen-action@v1.9.4
-      with:
-          doxyfile-path: docs/Doxyfile
-          working-directory: .
-          additional-packages: perl build-base biblatex ghostscript
-
+    - name: Build documentation
+      run: cmake --build build --target docs
     # Deploy the HTML documentation to GitHub Pages
     - name: GH Pages Deployment
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/html/
+        publish_dir: build/docs/html/
         enable_jekyll: false
         allow_empty_commit: false
         force_orphan: true

CMakeLists.txt

@@ -19,27 +19,10 @@ if (CMAKE_VERSION VERSION_LESS 3.21)
     endif ()
 endif ()
 option(KASSERT_BUILD_TESTS "Build the tests." ${PROJECT_IS_TOP_LEVEL})
+option(KASSERT_BUILD_DOCS "Build the tests." ${PROJECT_IS_TOP_LEVEL})
 
-if (PROJECT_IS_TOP_LEVEL)
-    # find Doxygen
-    find_package(Doxygen)
-    if (DOXYGEN_FOUND)
-        if (DOXYGEN_VERSION VERSION_LESS "1.9.2")
-            message(
-                WARNING
-                    "Doxygen must be version 1.9.2 or newer. Documentation may not be displayed correctly and CI may not pass even if checks pass locally."
-            )
-        endif ()
-        add_custom_target(
-            docs
-            COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_SOURCE_DIR}/docs/Doxyfile
-            WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
-            COMMENT "Generating Documentation"
-            VERBATIM
-        )
-    else ()
-        message(STATUS "Doxygen not found, not building docs")
-    endif ()
+if (KASSERT_BUILD_DOCS)
+  add_subdirectory(docs)
 endif ()
 
 add_library(kassert INTERFACE)

docs/CMakeLists.txt

@@ -0,0 +1,59 @@
+# find Doxygen
+find_package(Doxygen)
+
+if (DOXYGEN_FOUND)
+    if (DOXYGEN_VERSION VERSION_LESS "1.10.0")
+        message(
+            WARNING "Doxygen must be version 1.10.0 or newer. Documentation may not be displayed correctly and CI may "
+                    "not pass even if checks pass locally."
+        )
+    endif ()
+    include(FetchContent)
+    FetchContent_Declare(
+        doxygen-awesome-css
+        GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git
+        GIT_TAG v2.3.3
+    )
+    FetchContent_MakeAvailable(doxygen-awesome-css)
+
+    # required variables for setting up doxygen-awesome-css
+    set(DOXYGEN_GENERATE_TREEVIEW YES)
+    set(DOXYGEN_DISABLE_INDEX NO)
+    set(DOXYGEN_FULL_SIDEBAR NO)
+    set(DOXYGEN_HTML_EXTRA_STYLESHEET
+        ${doxygen-awesome-css_SOURCE_DIR}/doxygen-awesome.css
+        ${doxygen-awesome-css_SOURCE_DIR}/doxygen-awesome-sidebar-only.css
+        ${doxygen-awesome-css_SOURCE_DIR}/doxygen-awesome-sidebar-only-darkmode-toggle.css
+        ${CMAKE_CURRENT_LIST_DIR}/custom_doxygen/custom.css
+    )
+    set(DOXYGEN_HTML_EXTRA_FILES
+        ${doxygen-awesome-css_SOURCE_DIR}/doxygen-awesome-darkmode-toggle.js
+        ${doxygen-awesome-css_SOURCE_DIR}/doxygen-awesome-fragment-copy-button.js
+        ${doxygen-awesome-css_SOURCE_DIR}/doxygen-awesome-paragraph-link.js
+    )
+    set(DOXYGEN_HTML_HEADER ${CMAKE_CURRENT_LIST_DIR}/custom_doxygen/header.html)
+    set(DOXYGEN_HTML_FOOTER ${CMAKE_CURRENT_LIST_DIR}/custom_doxygen/footer.html)
+    set(DOXYGEN_HTML_COLORSTYLE LIGHT)
+
+    set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_LIST_DIR}/images/icon.svg")
+    set(DOXYGEN_IMAGE_PATH "${CMAKE_CURRENT_LIST_DIR}/images")
+    set(DOXYGEN_PREDEFINED KAMPING_DOXYGEN_ONLY)
+    set(DOXYGEN_GENERATE_TODOLIST NO)
+    set(DOXYGEN_EXTRACT_STATIC YES)
+    set(DOXYGEN_CASE_SENSE_NAMES YES)
+    set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
+    set(DOXYGEN_RECURSIVE YES)
+    set(DOXYGEN_STRIP_CODE_COMMENTS NO)
+    set(DOXYGEN_GENERATE_LATEX NO)
+    set(DOXYGEN_TAB_SIZE 2)
+    set(DOXYGEN_ENABLED_SECTIONS KAMPING_MAIN_PAGE)
+    set(DOXYGEN_FILE_PATTERNS *.cpp *.hpp *.dox *.md)
+
+    doxygen_add_docs(
+        docs ${CMAKE_CURRENT_LIST_DIR} ${CMAKE_CURRENT_LIST_DIR}/../include/
+        COMMENT "Generating Documentation"
+        WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/..
+    )
+else ()
+    message(STATUS "Doxygen not found, not building docs")
+endif ()