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,15 @@
+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: Create CMake config file
+      run: cmake -P ${{github.workspace}}/cmake/generate-doxygen-config.cmake
+    - 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()

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2019 Big Ladder Software, LLC
+Copyright (c) 2024 Big Ladder Software, LLC
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 

README.md

@@ -15,7 +15,7 @@ ctest -C Release
 
 - root
     - cmake
-    - docs
+    - doc
     - examples
     - include
     - src
@@ -31,17 +31,32 @@ This setup relies on the projects being managed in a Git repository.
 Manages the overall build with specific scripts for handling:
 
 - Defaulting build type (i.e., Release)
-- [Uniform compiler flags](cmake/compile-flags.cmake)
+- [Uniform compiler flags](cmake/build-options-interface.cmake)
 - Identifying build target architecture (i.e., operating system, compiler, and CPU instruction architecture) (TODO)
 - Automatic versioning based on Git repository tags (TODO)
 - Optional static or dynamic libraries
 - Handling of MSVC and Windows specific requirements (e.g., MT/MD flags, export headers)
 
-## Dependencies: Git submodules
+## Dependencies
+### Git submodules
 
 Where possible, dependencies are added using git submodules. In a few exceptional cases, a dependency may be vendored
 directly in the root repository.
 
+### Python / Poetry
+Some supporting functionality, such as building viewer-friendly web-hostable documentation, is implemented with [Python](https://python.org) and its libraries. We are currently supporting Python 3.7 and higher.
+
+This project uses the [Poetry](https://python-poetry.org/docs/#installation) python-package management tool. Python is used internally by the CMake build scripts; the CMake targets create a Poetry virtual environment in which the project's Python dependencies are installed, and in which commands are then run to build that target.
+
+### Clang format
+Use version 16+.
+
+*Be aware the the Github workflow for checking clang-format may give different results than your desktop version.
+
+### Documentation
+
+C++ in-source documentation is written with [Doxygen](https://doxygen.nl) comments (see [guidelines](./doc/guidelines.md)). As many open-source projects host customizable sphinx-style help pages for viewer-friendly consumption, the Atheneum workflow also converts
+
 ## Error handling (TODO)
 
 Consistent approach to handling error callbacks.

cmake/generate-doxygen-config.cmake

@@ -0,0 +1,12 @@
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg)
+
+message(STATUS ${DOXYFILE_IN})
+message(STATUS ${DOXYFILE_OUT})
+
+set(WARN_ON_DOC_ERROR "YES")
+set(DOXYGEN_INPUT_DIR include/${PROJECT_NAME})
+set(DOXYGEN_OUTPUT_DIR build)
+
+# Replace variables inside @@ with the current values
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

docs/CMakeLists.txt

@@ -0,0 +1,41 @@
+find_package(Doxygen REQUIRED)
+
+set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+set(WARN_ON_DOC_ERROR "YES")
+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(${PROJECT_NAME}_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(${PROJECT_NAME}_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")