docs: various updates (#79)

.codeql-prebuild-cpp-Linux.sh

@@ -20,11 +20,12 @@ sudo rm -rf /var/lib/apt/lists/*
 
 # build
 mkdir -p build
-cd build || exit 1
 cmake \
   -DBUILD_DOCS=OFF \
-  -G Ninja ..
-ninja
+  -B build \
+  -G Ninja \
+  -S .
+ninja -C build
 
 # skip autobuild
 echo "skip_autobuild=true" >> "$GITHUB_OUTPUT"

.codeql-prebuild-cpp-Windows.sh

@@ -15,11 +15,12 @@ pacman --noconfirm -S \
 
 # build
 mkdir -p build
-cd build || exit 1
 cmake \
   -DBUILD_DOCS=OFF \
-  -G Ninja ..
-ninja
+  -B build \
+  -G Ninja \
+  -S .
+ninja -C build
 
 # skip autobuild
 echo "skip_autobuild=true" >> "$GITHUB_OUTPUT"

.codeql-prebuild-cpp-macOS.sh

@@ -10,11 +10,12 @@ brew install \
 
 # build
 mkdir -p build
-cd build || exit 1
 cmake \
   -DBUILD_DOCS=OFF \
-  -G Ninja ..
-ninja
+  -B build \
+  -G Ninja \
+  -S .
+ninja -C build
 
 # skip autobuild
 echo "skip_autobuild=true" >> "$GITHUB_OUTPUT"

.github/workflows/ci.yml

@@ -63,21 +63,20 @@ jobs:
           sudo apt-get install -y \
             build-essential \
             cmake \
-            doxygen \
-            graphviz \
             ninja-build \
             nlohmann-json3-dev
 
       - name: Setup Dependencies macOS
         if: runner.os == 'macOS'
         run: |
           brew install \
+            boost \
             cmake \
             doxygen \
             graphviz \
+            nlohmann-json \
             ninja \
-            boost \
-            nlohmann-json
+            node \
 
       - name: Setup Dependencies Windows
         if: runner.os == 'Windows'
@@ -91,6 +90,7 @@ jobs:
             mingw-w64-ucrt-x86_64-cmake
             mingw-w64-ucrt-x86_64-graphviz
             mingw-w64-ucrt-x86_64-ninja
+            mingw-w64-ucrt-x86_64-nodejs
             mingw-w64-ucrt-x86_64-toolchain
             mingw-w64-ucrt-x86_64-boost
             mingw-w64-ucrt-x86_64-nlohmann-json
@@ -177,18 +177,27 @@ jobs:
           COMMIT: ${{ needs.setup_release.outputs.release_commit }}
         run: |
           mkdir -p build
-          cd build
+
+          if [ "${{ runner.os }}" = "Linux" ]; then
+            # Doxygen from Ubuntu is too old, need Doxygen >= 1.10
+            DOCS=OFF
+          else
+            DOCS=ON
+          fi
+
           cmake \
+            -DBUILD_DOCS=${DOCS} \
             -DCMAKE_BUILD_TYPE:STRING=Debug \
+            -B build \
             -G Ninja \
-            ..
-          ninja
+            -S .
+          ninja -C build
 
       - name: Run tests
         id: test
-        working-directory: build
+        working-directory: build/tests
         run: |
-          ./tests/test_libdisplaydevice --gtest_color=yes
+          ./test_libdisplaydevice --gtest_color=yes
 
       - name: Generate gcov report
         # any except canceled or skipped

.gitignore

@@ -41,5 +41,8 @@
 build/
 cmake-*/
 
+# doxyconfig
+docs/*-doxyconfig*
+
 # CTest
 Testing/

.gitmodules

@@ -1,7 +1,7 @@
-[submodule "third-party/doxygen-awesome-css"]
-	path = third-party/doxygen-awesome-css
-	url = https://github.com/jothepro/doxygen-awesome-css.git
-	branch = main
+[submodule "third-party/doxyconfig"]
+	path = third-party/doxyconfig
+	url = https://github.com/LizardByte/doxyconfig.git
+	branch = master
 [submodule "third-party/googletest"]
 	path = third-party/googletest
 	url = https://github.com/google/googletest.git

.readthedocs.yaml

@@ -3,25 +3,37 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the version of Python
 build:
   os: ubuntu-24.04
   tools:
     python: "miniconda-latest"
   commands:
     # because we are overriding the build commands, we need to setup the environment ourselves
-    - cat docs/environment.yml
-    - conda env create --quiet --name $READTHEDOCS_VERSION --file docs/environment.yml
-    - cmake -B build -S .
-    - cmake --build build --target docs
+    - cat third-party/doxyconfig/environment.yml
+    - conda env create --quiet --name ${READTHEDOCS_VERSION} --file third-party/doxyconfig/environment.yml
+    - npm install "@fortawesome/fontawesome-free"
+    - mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
+    - mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
+    - cp node_modules/@fortawesome/fontawesome-free/css/all.min.css ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
+    - cp node_modules/@fortawesome/fontawesome-free/js/all.min.js ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
+    - cp -r node_modules/@fortawesome/fontawesome-free/webfonts ${READTHEDOCS_OUTPUT}html/assets/fontawesome/
+    - |
+      wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico" \
+        -O ${READTHEDOCS_OUTPUT}lizardbyte.ico
+    - |
+      wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png" \
+        -O ${READTHEDOCS_OUTPUT}lizardbyte.png
+    - cp ./third-party/doxyconfig/Doxyfile ./docs/Doxyfile-doxyconfig
+    - cp ./third-party/doxyconfig/header.html ./docs/header-doxyconfig.html
+    - cat ./docs/Doxyfile >> ./docs/Doxyfile-doxyconfig
+    - cd docs && doxygen Doxyfile-doxyconfig
 
 # using conda, we can get newer doxygen and graphviz than ubuntu provide
 # https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661
 conda:
-  environment: docs/environment.yml
+  environment: third-party/doxyconfig/environment.yml
 
 submodules:
   include: all

CMakeLists.txt

@@ -16,7 +16,7 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
 endif()
 
 # Add our custom CMake modules to the global path
-list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
 
 #
 # Project optional configuration
@@ -28,7 +28,7 @@ option(BUILD_TESTS "Build tests" ON)
 # Documentation
 #
 if(BUILD_DOCS)
-    add_subdirectory(docs)
+    add_subdirectory(third-party/doxyconfig docs)
 endif()
 
 #

README.md

@@ -23,8 +23,7 @@ Ensure [git](https://git-scm.com/) is installed and run the following:
 ```bash
 git clone https://github.com/lizardbyte/libdisplaydevice.git --recurse-submodules
 cd libdisplaydevice
-mkdir build
-cd build
+mkdir -p build
 ```
 
 ### Windows
@@ -54,18 +53,17 @@ pacman -S \
 
 ### Build
 
-> [!WARNING]
-> Ensure you are in the build directory created during the clone step earlier before continuing.
+@warning{Ensure you are in the build directory created during the clone step earlier before continuing.}
 
 ```bash
-cmake -G Ninja ..
-ninja
+cmake -G Ninja -B build -S .
+ninja -C build
 ```
 
 ### Test
 
 ```bash
-tests\test_libdisplaydevice
+./build/tests/test_libdisplaydevice
 ```
 
 ## Support

docs/Doxyfile

@@ -21,80 +21,22 @@
 # replacement variables:
 # doxygen -x_noenv [configFile]
 
-# must be first
-DOXYFILE_ENCODING = UTF-8
-
-# files and directories to process
-INPUT = ../README.md \
-        ../src
-
-ALIASES = ""
-ALIASES += "examples=^^**Examples**^^@code{.cpp}"
-ALIASES += "examples_end=@endcode^^"
-ALIASES += "rst=^^\verbatim embed:rst:leading-asterisk^^"
-ALIASES += "rst_end=\endverbatim"
-
-CASE_SENSE_NAMES = YES
-DISABLE_INDEX = NO
-DOCBOOK_OUTPUT = doxydocbook
+# project metadata
 DOCSET_BUNDLE_ID = dev.lizardbyte.libdisplaydevice
 DOCSET_PUBLISHER_ID = dev.lizardbyte.libdisplaydevice.documentation
-DOCSET_PUBLISHER_NAME = LizardByte
-DOT_GRAPH_MAX_NODES = 50
-DOT_IMAGE_FORMAT = svg
-
-# TODO: On Windows, Doxygen hangs when creating dot graphs if this is set to 0
-DOT_NUM_THREADS = 1
-
-EXTRACT_ALL = NO
-FULL_SIDEBAR = NO
-GENERATE_HTML = YES
-GENERATE_LATEX = NO
-GENERATE_TREEVIEW = YES
-GENERATE_XML = NO
-HAVE_DOT = YES
-HTML_COLORSTYLE = LIGHT  # required with Doxygen >= 1.9.5
-HTML_COPY_CLIPBOARD = NO  # required for Doxygen >= 1.10.0
-HTML_EXTRA_FILES = ../third-party/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
-HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
-HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
-HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
-HTML_EXTRA_STYLESHEET = ../third-party/doxygen-awesome-css/doxygen-awesome.css
-HTML_HEADER = doxygen/header.html
-HTML_OUTPUT = html
-# INCLUDE_PATH = ../
-INTERACTIVE_SVG = YES
-LATEX_OUTPUT = latex
-MACRO_EXPANSION = YES
-MAN_OUTPUT = man
-NUM_PROC_THREADS = 1
-PREDEFINED = DOXYGEN
-PREDEFINED += __APPLE__
-PREDEFINED += linux
-PREDEFINED += __linux
-PREDEFINED += __linux__
-PREDEFINED += __MACH__
-PREDEFINED += _WIN32
 PROJECT_BRIEF = "C++ library to modify display devices."
-PROJECT_ICON = $(LDD_DOXYGEN_BUILD_DIR)/lizardbyte.ico
-PROJECT_NUMBER = $(LDD_PROJECT_VERSION)
-PROJECT_LOGO = $(LDD_DOXYGEN_BUILD_DIR)/lizardbyte.png
 PROJECT_NAME = libdisplaydevice
-OUTPUT_DIRECTORY = $(LDD_DOXYGEN_BUILD_DIR)
-RECURSIVE = YES
-RTF_OUTPUT = rtf
-SORT_BRIEF_DOCS = YES
-STRIP_FROM_INC_PATH = ../
-STRIP_FROM_PATH = ../
-WARN_AS_ERROR = FAIL_ON_WARNINGS
+
+# project specific settings
+DOT_GRAPH_MAX_NODES = 50
+# IMAGE_PATH = ../docs/images
+INCLUDE_PATH =
 
 # TODO: Enable this when we have complete documentation
 WARN_IF_UNDOCUMENTED = NO
 
-WARN_IF_DOC_ERROR = YES
-WARN_IF_INCOMPLETE_DOC = YES
-WARN_IF_UNDOC_ENUM_VAL = YES
-WARN_NO_PARAMDOC = YES
-WARNINGS = YES
-
-XML_OUTPUT = xml
+# files and directories to process
+USE_MDFILE_AS_MAINPAGE = ../README.md
+INPUT = ../README.md \
+        ../third-party/doxyconfig/docs/source_code.md \
+        ../src