Build doxygen and sphinx (read-the-docs style) docs using cmake -D{project}_BUILD_DOCUMENTATION

.clang-format

@@ -128,7 +128,7 @@ IndentPPDirectives: None
 IndentRequiresClause: true
 IndentWidth:     4
 IndentWrappedFunctionNames: false
-InsertBraces:    false
+InsertBraces:    true
 InsertNewlineAtEOF: true
 InsertTrailingCommas: None
 IntegerLiteralSeparator:

.github/workflows/doxygen-completeness-check.yml

@@ -0,0 +1,13 @@
+name: Doxygen Consistency Check
+on: [push, pull_request]
+jobs:
+  doxygen-completeness-check:
+    name: Doxygen completeness check
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Run doxygen for C++ programs.
+      uses: mattnotmitt/[email protected]
+      with:
+          working-directory: '.'
+          doxyfile-path: 'doxygen.cfg'

CMakeLists.txt

@@ -52,3 +52,9 @@ if (${PROJECT_NAME}_BUILD_TESTING)
         coverage_evaluate()
     endif ()
 endif ()
+
+find_package(Doxygen)
+
+if (${PROJECT_NAME}_BUILD_DOCUMENTATION)
+  add_subdirectory(docs)
+endif()

cmake/FindSphinx.cmake

@@ -0,0 +1,11 @@
+#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,40 @@
+find_package(Doxygen REQUIRED)
+
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/include/${PROJECT_NAME})
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
+set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
+file(GLOB_RECURSE project_public_headers ${DOXYGEN_INPUT_DIR}/*.h)
+
+# 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 ${project_public_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}/sphinx-source)
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_PROGRAM "sphinx-build")
+
+# The poetry (dependency) installation is performed below as part of the target's command sequence.
+# The order of operations is important: 1. Install sphinx/breathe as part of the project's dependencies
+# 2. Find or assert the path to sphinx, 3. Run sphinx/breathe
+# Note that "poetry run" during CMake's build phase does not activate an environment installed
+# during CMake's configuration phase!
+
+add_custom_target(Sphinx ALL
+                  COMMAND poetry install
+                  COMMAND poetry run ${SPHINX_PROGRAM} -b html
+                  -Dbreathe_projects.${PROJECT_NAME}=${DOXYGEN_OUTPUT_DIR}/xml
+                  ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                  WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+                  COMMENT "Generating documentation with Sphinx")