fix: Add documentation workflow and awesome documentation

coin3d · May 14, 2024 · 2858528 · 2858528
1 parent 549e633
commit 2858528
Show file tree

Hide file tree

Showing 6 changed files with 570 additions and 1 deletion.
diff --git a/.github/workflows/documentation-workflow.yml b/.github/workflows/documentation-workflow.yml
@@ -0,0 +1,49 @@
+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 doxygen graphviz freeglut3-dev qtbase5-dev qttools5-dev libxi-dev
+          mkdir cmake_download_dir
+          DOWNLOAD_FILE_COIN=coin-latest-Ubuntu2204-gcc11-x64.tar.gz
+          RELEASE_ID=`curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/coin3d/coin/releases | jq -r --arg COIN_REPO_TAG_NAME "CI-builds" '.[] | select(.tag_name==$COIN_REPO_TAG_NAME) | .id'`
+          ASSET_ID=`curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/coin3d/coin/releases/$RELEASE_ID | jq -r --arg DOWNLOAD_FILE_COIN "$DOWNLOAD_FILE_COIN" '.assets[] | select(.name==$DOWNLOAD_FILE_COIN) | .id'`
+          export DOWNLOAD_ADDRESS_COIN=https://api.github.com/repos/coin3d/coin/releases/assets/$ASSET_ID
+          echo download file $DOWNLOAD_FILE_COIN from address $DOWNLOAD_ADDRESS_COIN
+          curl -s -S -L -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" -H "Accept: application/octet-stream" -o $DOWNLOAD_FILE_COIN $DOWNLOAD_ADDRESS_COIN
+          tar xzf $DOWNLOAD_FILE_COIN -C cmake_download_dir
+          DOWNLOAD_FILE_SOQT=soqt-latest-Qt5-Ubuntu2204-gcc11-x64.tar.gz
+          RELEASE_ID=`curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/coin3d/soqt/releases | jq -r --arg SOQT_REPO_TAG_NAME "CI-builds" '.[] | select(.tag_name==$SOQT_REPO_TAG_NAME) | .id'`
+          ASSET_ID=`curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/coin3d/soqt/releases/$RELEASE_ID | jq -r --arg DOWNLOAD_FILE_SOQT "$DOWNLOAD_FILE_SOQT" '.assets[] | select(.name==$DOWNLOAD_FILE_SOQT) | .id'`
+          export DOWNLOAD_ADDRESS_SOQT=https://api.github.com/repos/coin3d/soqt/releases/assets/$ASSET_ID
+          echo download file $DOWNLOAD_FILE_SOQT from address $DOWNLOAD_ADDRESS_SOQT
+          curl -s -S -L -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" -H "Accept: application/octet-stream" -o $DOWNLOAD_FILE_SOQT $DOWNLOAD_ADDRESS_SOQT
+          tar xzf $DOWNLOAD_FILE_SOQT -C cmake_download_dir
+          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 -DCMAKE_PREFIX_PATH=cmake_download_dir/Coin3D -DNUTSNBOLTS_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
diff --git a/.gitmodules b/.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
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -57,6 +57,7 @@ option(NUTSNBOLTS_USE_QT6 "Prefer Qt6 over Qt5 if available" ON)
 option(NUTSNBOLTS_USE_QT5 "Prefer Qt5 over Qt4 if available" ON)
 option(NUTSNBOLTS_USE_WX "Prefer wxWidgets over Qt if available" OFF)
 option(NUTSNBOLTS_BUILD_DOCUMENTATION "Build and install API documentation (requires Doxygen)." OFF)
+option(NUTSNBOLTS_BUILD_AWESOME_DOCUMENTATION "Build and install API documentation in new modern style (requires Doxygen)." OFF)
 cmake_dependent_option(NUTSNBOLTS_BUILD_INTERNAL_DOCUMENTATION "Document internal code not part of the API." OFF "NUTSNBOLTS_BUILD_DOCUMENTATION" OFF)
 cmake_dependent_option(NUTSNBOLTS_BUILD_DOC_MAN "Build NutsnBolts man pages." OFF "NUTSNBOLTS_BUILD_DOCUMENTATION" OFF)
 cmake_dependent_option(NUTSNBOLTS_BUILD_DOC_QTHELP "Build QtHelp documentation." OFF "NUTSNBOLTS_BUILD_DOCUMENTATION" OFF)
@@ -69,6 +70,7 @@ report_prepare(
   NUTSNBOLTS_USE_QT5
   NUTSNBOLTS_USE_WX
   NUTSNBOLTS_BUILD_DOCUMENTATION
+  NUTSNBOLTS_BUILD_AWESOME_DOCUMENTATION
   NUTSNBOLTS_BUILD_INTERNAL_DOCUMENTATION
   NUTSNBOLTS_BUILD_DOC_MAN
   NUTSNBOLTS_BUILD_DOC_QTHELP

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -89,7 +89,6 @@ if(NUTSNBOLTS_BUILD_DOCUMENTATION)
 # ############################################################################
 # Setup documentation targets
 # ############################################################################
-
   add_custom_command(
     OUTPUT ${DOXYGEN_OUTPUT}
     COMMAND ${CMAKE_COMMAND} -E echo_append "Generating API documentation with Doxygen "
@@ -115,3 +114,97 @@ if(NUTSNBOLTS_BUILD_DOCUMENTATION)
     message(STATUS "CMAKE_INSTALL_MANDIR ${CMAKE_INSTALL_MANDIR}")
   endif()
 endif()
+
+# Add a target to generate new modern API documentation with Doxygen
+if(NUTSNBOLTS_BUILD_AWESOME_DOCUMENTATION)
+  find_package(Doxygen)
+  if(NOT DOXYGEN_FOUND)
+    message(FATAL_ERROR "Doxygen is needed to build the documentation.")
+  endif()
+
+  if(NOT "${Coin_DOC_DIR}" STREQUAL "")
+    get_filename_component(_coin_versioned_dir ${Coin_DOC_DIR} NAME)
+    set(DOXYGEN_TAGFILES_AWESOME "${Coin_DOC_DIR}/html/Coin.tag=../../${_coin_versioned_dir}/html_awesome")
+  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/nutsnbolts")
+  if(NUTSNBOLTS_BUILD_INTERNAL_DOCUMENTATION)
+    set(DOXYGEN_EXTRACT_PRIVATE YES)
+    set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
+    set(DOXYGEN_INTERNAL_DOCS YES)
+    set(NB_DOCUMENTATION_FILES
+      ${NB_DOCUMENTATION_FILES}
+      ${NB_INTERNAL_DOCUMENTATION_FILES}
+      CACHE INTERNAL "NB_DOCUMENTATION_FILES"
+    )
+  else()
+    set(NB_DOCUMENTATION_EXCLUDE_SYMBOLS SoProfilerP)
+    foreach(XF ${NB_INTERNAL_DOCUMENTATION_FILES})
+      set(DOXYGEN_EXCLUDE "${DOXYGEN_EXCLUDE}                         ${XF} \\\n")
+    endforeach(XF)
+  endif()
+  set(DOXYGEN_INPUT)
+  list(REMOVE_DUPLICATES NB_DOCUMENTATION_FILES)
+  foreach(XF ${NB_DOCUMENTATION_FILES})
+    set(DOXYGEN_INPUT "${DOXYGEN_INPUT}                         ${XF} \\\n")
+  endforeach(XF)
+  dump_variable(
+  NB_DOCUMENTATION_FILES
+  DOXYGEN_INPUT
+  )
+  set(DOXYGEN_EXCLUDE_SYMBOLS)
+  foreach(XF ${NB_DOCUMENTATION_EXCLUDE_SYMBOLS})
+    set(DOXYGEN_EXCLUDE_SYMBOLS "${DOXYGEN_EXCLUDE_SYMBOLS}                         ${XF} \\\n")
+  endforeach(XF)
+
+  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")
+  dump_variable(DOXYGEN_TAGFILES)
+  configure_file("${CMAKE_SOURCE_DIR}/docs/nutsnbolts.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()
diff --git a/docs/doxygen-awesome b/docs/doxygen-awesome