Document with Sphinx

.github/workflows/documentation.yml

@@ -0,0 +1,33 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - uses: awalsh128/cache-apt-pkgs-action@latest
+        with:
+          packages: doxygen doxygen-doc doxygen-gui doxygen-latex graphviz mscgen python3-breathe python3-sphinx python3-sphinx-rtd-theme
+          version: 1.0
+
+      - name: Configure CMake
+        run: |
+          # In fact, POLYM_BUILD_DOCS is on by default
+          cmake -B ${{github.workspace}}/build -DPOLYM_BUILD_DOCS=ON
+      - name: Sphinx build
+        run: |
+          cmake --build build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/document' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{github.workspace}}/build/docs/sphinx
+          force_orphan: true

.gitignore

@@ -0,0 +1,8 @@
+.vscode
+build
+_build
+cmake-debug-build
+docs/build
+
+# Documentation toolchain
+sphinx_*/

CMakeLists.txt

@@ -1,10 +1,13 @@
 cmake_minimum_required(VERSION 3.8)
 
 option(POLYM_BUILD_TEST "Build test with Polym" OFF)
+option(POLYM_BUILD_DOCS "Build docs with Polym" ON)
 
 project(PolyM)
 
-add_library(polym 
+set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+
+add_library(polym
     src/Msg.cpp
     src/Queue.cpp
 
@@ -25,4 +28,31 @@ if(POLYM_BUILD_TEST)
   target_link_libraries(testpolym polym)
   target_include_directories(testpolym PRIVATE test/)
   add_test(NAME PolyM COMMAND testpolym)
-endif()
+endif()
+
+function(check_python_module module)
+  execute_process(
+    COMMAND ${Python3_EXECUTABLE} -c "import ${module}"
+    RESULT_VARIABLE result
+    ERROR_QUIET
+  )
+  if(NOT result EQUAL 0)
+    message(FATAL_ERROR "Python module '${module}' not found")
+  else()
+    message(STATUS "Found Python module '${module}'")
+  endif()
+endfunction()
+
+if(POLYM_BUILD_DOCS)
+  find_package(Doxygen REQUIRED)
+  find_package(Sphinx REQUIRED)
+  find_package(Python3 REQUIRED COMPONENTS Interpreter)
+  check_python_module(breathe)
+  check_python_module(sphinx_rtd_theme)
+  set_property(
+    TARGET polym
+    PROPERTY PUBLIC_INCLUDE_DIRECTORIES
+    ${CMAKE_CURRENT_LIST_DIR}/include/polym
+  )
+  add_subdirectory(docs)
+endif()

cmake/FindSphinx.cmake

@@ -0,0 +1,12 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)
+

docs/CMakeLists.txt

@@ -0,0 +1,49 @@
+cmake_minimum_required(VERSION 3.8)
+
+find_package(Doxygen REQUIRED)
+find_package(Sphinx REQUIRED)
+
+# Find header
+get_target_property(HEADER_DIR polym PUBLIC_INCLUDE_DIRECTORIES)
+file(GLOB_RECURSE HEADERS ${HEADER_DIR}/*.h)
+
+set(DOXYGEN_INPUT_DIR ${HEADER_DIR})
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/build)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+#Replace variables inside @@ with the current values
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) #Doxygen won't create this for us
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+                   DEPENDS ${HEADERS}
+                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+                   COMMENT "Generating docs")
+
+add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/source)
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+# Only regenerate Sphinx when:
+# - Doxygen has rerun
+# - Our doc files have been updated
+# - The Sphinx config has been updated
+add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
+                   COMMAND
+                     ${SPHINX_EXECUTABLE} -b html
+                     # Tell Breathe where to find the Doxygen output
+                     -Dbreathe_projects.polym=${DOXYGEN_OUTPUT_DIR}/xml
+                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                   DEPENDS
+                   # Other docs files you want to track should go here (or in some variable)
+                   ${SPHINX_SOURCE}/index.rst
+                   ${DOXYGEN_INDEX_FILE}
+                   MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+                   COMMENT "Generating documentation with Sphinx")
+add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})