fix: Add documentation workflow and awesome documentation

.github/workflows/documentation-workflow.yml

@@ -0,0 +1,34 @@
+name: Awesome Documentation Build
+
+on:
+  workflow_dispatch:  # Allow manual triggers
+  push:
+    branches: [ master ]
+
+jobs:
+  ubuntu-build:
+    name: Ubuntu Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Create build directory and run CMake
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install libpng-dev libjpeg-dev libgif-dev libtiff-dev libogg-dev libvorbis-dev libsndfile-dev zlib1g-dev
+          curl -L -o doxygen-1.10.0.linux.bin.tar.gz https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.linux.bin.tar.gz
+          tar xzf doxygen-1.10.0.linux.bin.tar.gz
+          export PATH=${{ github.workspace }}/doxygen-1.10.0/bin:$PATH
+          cmake -S . -B cmake_build_dir -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=cmake_install_dir -DSIMAGE_BUILD_AWESOME_DOCUMENTATION=ON
+      - name: Build project
+        run: |
+          export PATH=${{ github.workspace }}/doxygen-1.10.0/bin:$PATH
+          doxygen --version
+          cmake --build cmake_build_dir --target documentation_awesome --config Release -- -j4
+      - name: Deploy Awesome Documentation to Github Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: cmake_build_dir/html_awesome

.gitmodules

@@ -1,3 +1,7 @@
 [submodule "cpack.d"]
 	path = cpack.d
 	url = https://github.com/coin3d/cpack.d
+[submodule "docs/doxygen-awesome"]
+	path = docs/doxygen-awesome
+	url = https://github.com/coin3d/doxygen-awesome-css.git
+	branch = coin3d

CMakeLists.txt

@@ -58,6 +58,7 @@ option(SIMAGE_BUILD_SHARED_LIBS "Build shared libraries" ON)
 option(SIMAGE_BUILD_EXAMPLES "Build examples" ON)
 option(SIMAGE_BUILD_TESTS "Build tests" ON)
 option(SIMAGE_BUILD_DOCUMENTATION "Build and install API documentation (requires Doxygen)." OFF)
+option(SIMAGE_BUILD_AWESOME_DOCUMENTATION "Build and install API documentation in new modern style (requires Doxygen)." OFF)
 cmake_dependent_option(SIMAGE_USE_AVIENC "Use Video for Windows for AVI encoding" ON "WIN32" OFF)
 cmake_dependent_option(SIMAGE_USE_GDIPLUS "Use GDI+ on Windows to load/save images" ON "WIN32" OFF)
 cmake_dependent_option(SIMAGE_USE_CGIMAGE "Use CGImage on OS X to load/save images" ON "APPLE" OFF)
@@ -191,6 +192,7 @@ cmake_dependent_option(SIMAGE_TIFF_SUPPORT "Enable support for TIFF images" ON "
 report_prepare(
   SIMAGE_BUILD_SHARED_LIBS
   SIMAGE_BUILD_DOCUMENTATION
+  SIMAGE_BUILD_AWESOME_DOCUMENTATION
   SIMAGE_USE_QIMAGE
   SIMAGE_USE_QT5
   SIMAGE_LIBJASPER_SUPPORT
@@ -753,6 +755,66 @@ if(SIMAGE_BUILD_DOCUMENTATION)
   install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html" DESTINATION ${CMAKE_INSTALL_DOCDIR} COMPONENT documentation REGEX ".*\\.(chm|qch)" EXCLUDE)
 endif()
 
+# Add a target to generate new modern API documentation with Doxygen
+if(SIMAGE_BUILD_AWESOME_DOCUMENTATION)
+  find_package(Doxygen)
+  if(NOT DOXYGEN_FOUND)
+    message(FATAL_ERROR "Doxygen is needed to build the documentation.")
+  endif()
+
+  find_package(Git QUIET)
+  if(GIT_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
+  # Update submodules as needed
+      option(GIT_SUBMODULE "Check submodules during build" ON)
+      if(GIT_SUBMODULE)
+          message(STATUS "Submodule update")
+          execute_process(COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive
+                          WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                          RESULT_VARIABLE GIT_SUBMOD_RESULT)
+          if(NOT GIT_SUBMOD_RESULT EQUAL "0")
+              message(FATAL_ERROR "git submodule update --init --recursive failed with ${GIT_SUBMOD_RESULT}, please checkout submodules")
+          endif()
+      endif()
+  endif()
+
+# ############################################################################
+# Setup documentation options
+# ############################################################################
+  set(GENERATE_HTMLHELP NO)
+  set(DOXYGEN_GENERATE_MAN NO)
+  set(GENERATE_QHP NO)
+  set(GENERATE_TREEVIEW YES)
+  set(DOXYGEN_INTERNAL_DOCS NO)
+  set(DOXYGEN_EXTRACT_PRIVATE NO)
+  set(DOXYGEN_WARN_IF_UNDOCUMENTED YES)
+  set(DOXYGEN_EXCLUDE)
+  set(GITHUB_LINK "https://github.com/coin3d/simage")
+
+  set(DOXYFILE_AWESOME "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_awesome")
+  set(HTML_HEADER_AWESOME "${CMAKE_BINARY_DIR}/header_awesome.html")
+  set(DOXYGEN_OUTPUT_AWESOME "${CMAKE_BINARY_DIR}/html_awesome/index.html")
+  configure_file("${CMAKE_SOURCE_DIR}/docs/simage.doxygen.awesome.cmake.in" ${DOXYFILE_AWESOME} @ONLY)
+  configure_file("${CMAKE_SOURCE_DIR}/docs/doxygen-awesome/doxygen-custom/header.html.cmake.in" ${HTML_HEADER_AWESOME} @ONLY)
+
+# ############################################################################
+# Setup documentation targets
+# ############################################################################
+  add_custom_command(
+    OUTPUT ${DOXYGEN_OUTPUT_AWESOME}
+    COMMAND ${CMAKE_COMMAND} -E echo_append "Generating modern API documentation with Doxygen "
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_AWESOME}
+    COMMAND ${CMAKE_COMMAND} -E echo "done."
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
+    DEPENDS ${DOXYFILE_AWESOME}
+  )
+  add_custom_target(documentation_awesome ALL DEPENDS ${DOXYGEN_OUTPUT_AWESOME})
+
+# ############################################################################
+# Install built documentation files
+# ############################################################################
+  install(DIRECTORY "${CMAKE_BINARY_DIR}/html_awesome" DESTINATION ${CMAKE_INSTALL_DOCDIR} COMPONENT documentation REGEX ".*\\.(chm|qch)" EXCLUDE)
+endif()
+
 # ############################################################################
 # Install headers
 # ############################################################################