fix: Add documentation workflow and awesome documentation

.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

.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

@@ -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

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()