Feature/documentation and logging

.github/workflows/release.yml

@@ -34,10 +34,14 @@ jobs:
                   echo "Building Linux"
                   cmake --workflow --preset package-release-debian-${{matrix.build-variant}}-workflow
               shell: bash
+            - name: Create a zip file with specific files/folders
+              shell: powershell
+              run: |
+                  Compress-Archive -Path "${{ github.workspace }}/build/${{ matrix.build-variant }}/*.deb" -DestinationPath "${{ matrix.build-variant }}.zip"
             - name: Upload Debian Package to Release
               uses: svenstaro/upload-release-action@v2
               with:
                   repo_token: ${{ secrets.GITHUB_TOKEN }}
-                  file: ${{ github.workspace }}/build/${{ matrix.build-variant }}/*.deb
+                  file: "${{ matrix.build-variant }}.zip"
                   file_glob: true
                   tag: ${{ github.ref }}

.github/workflows/unit-testing.yml

@@ -63,5 +63,5 @@ jobs:
                       echo "Testing Microsoft"
                       cmake --workflow --preset test-debug-microsoft-${{matrix.build-variant}}-workflow
                   fi
-              timeout-minutes: 5
+              timeout-minutes: 7
               shell: bash

.gitignore

@@ -3,6 +3,8 @@
 # To modify the Doxyfile, edit docs/Doxyfile.in and re-run CMake. It will build the new Doxyfile at the root of the build tree.
 Doxyfile
 
+*.log
+
 .metadata
 bin/
 tmp/

CMakeLists.txt

@@ -73,7 +73,7 @@ endif()
 add_library(respond_model)
 add_library(respond::respond_model ALIAS respond_model)
 
-file(GLOB_RECURSE RESPOND_HEADERS include/respond/*.hpp)
+file(GLOB_RECURSE RESPOND_HEADERS include/respond/*.hpp include/respond/*.h)
 file(GLOB RESPOND_INTERNAL_HEADERS CONFIGURE_DEPENDS src/internals/*.hpp)
 file(GLOB RESPOND_SOURCE_FILES CONFIGURE_DEPENDS src/*.cpp)
 

CMakePresets.json

@@ -124,6 +124,23 @@
                 "default-respond-config"
             ]
         },
+        {
+            "name": "benchmark-linux-static-config",
+            "displayName": "Benchmark, Linux, Static",
+            "description": "Target a linux distro to build release benchmark artifacts",
+            "inherits": [
+                "release-config",
+                "linux-config",
+                "static-config",
+                "default-respond-config"
+            ],
+            "cacheVariables": {
+                "RESPOND_BUILD_BENCH": "ON",
+                "RESPOND_BUILD_TESTS": "OFF",
+                "RESPOND_BUILD_DOCS": "OFF",
+                "RESPOND_INSTALL": "OFF"
+            }
+        },
         {
             "name": "debug-microsoft-shared-config",
             "displayName": "Debug, Microsoft, Shared",
@@ -199,6 +216,12 @@
             "inherits": "default-build",
             "configurePreset": "debug-linux-static-config"
         },
+        {
+            "name": "benchmark-linux-static-build",
+            "displayName": "Benchmark Linux Static Build",
+            "inherits": "default-build",
+            "configurePreset": "benchmark-linux-static-config"
+        },
         {
             "name": "release-microsoft-shared-build",
             "displayName": "Release Microsoft Shared Build",
@@ -411,6 +434,21 @@
                 }
             ]
         },
+        {
+            "name": "benchmark-linux-static-workflow",
+            "displayName": "Benchmark, Linux, Static",
+            "description": "Build benchmark artifacts for performance testing.",
+            "steps": [
+                {
+                    "type": "configure",
+                    "name": "benchmark-linux-static-config"
+                },
+                {
+                    "type": "build",
+                    "name": "benchmark-linux-static-build"
+                }
+            ]
+        },
         {
             "name": "package-release-debian-shared-workflow",
             "displayName": "Package, Release, Debian, Shared",

Doxyfile.in

@@ -48,7 +48,7 @@ PROJECT_NAME           = RESPOND
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.3.2
+PROJECT_NUMBER         = 2.4.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

README.md

@@ -22,12 +22,13 @@ The [original RESPOND model](https://github.com/SyndemicsLab/RESPONDv1/tree/main
 
 RESPOND makes full use of the CMake build system. It is a common tool used throughout the C++ user-base and we utilize it for dependency management, linking, and testing. As C++ has poor package management, we intentionally decided to move our focus away from tools such as conan and vcpkg and stay with pure CMake. Not to say we would never publish with such package managers, but it is not a core focus of the refactor/engineering team.
 
-We natively support 4 different build workflows with the `CMakePresets.json` file. They are:
+We natively support 5 different build workflows with the `CMakePresets.json` file. They are:
 
 1. `test-debug-gcc-linux-shared-workflow`
 2. `test-debug-gcc-linux-static-workflow`
 3. `package-release-gcc-linux-shared-workflow`
 4. `package-release-gcc-linux-static-workflow`
+5. `benchmark-linux-static-workflow`
 
 These workflows follow the pattern `{function}-{build}-gcc-linux-{library}-workflow` and have corresponding presets for build, test, and package. As we adopt more operating systems and compilers we will expand beyond gcc and linux.
 
@@ -105,14 +106,76 @@ tools/build.sh
 
 ## Running RESPOND
 
-The recommended way to use the RESPOND model is via the [Python
-package][respondpy], with [source on GitHub][respondpy-git].
+The recommended way to use the RESPOND model is via the [Python package][respondpy], with [source on GitHub][respondpy-git].
 
-If you wish to use RESPOND via a local executable, please refer to release
-[v0.3.0](https://github.com/SyndemicsLab/respond/releases/tag/v0.3.0).
+For C++ developers wishing to use RESPOND as a library, please refer to the [C++ API Guide][api-guide] in the documentation for usage examples, design patterns, and best practices.
+
+If you wish to use RESPOND via a legacy local executable, please refer to release [v0.3.0](https://github.com/SyndemicsLab/respond/releases/tag/v0.3.0).
+
+## Documentation
+
+Complete documentation is available in the [`docs/src/`](docs/src) directory:
+
+- **[C++ API Guide][api-guide]** - Developer guide for using RESPOND as a C++ library
+- **[Architecture and Design](docs/src/architecture.md)** - Design patterns, component architecture, and extensibility
+- **[Data Management](docs/src/data.md)** - Configuration files and data requirements
+- **[Installation](docs/src/installation.md)** - Build and installation instructions
+- **[Running the Model](docs/src/run.md)** - Execution instructions
+- **[Math Background](docs/src/math.md)** - Mathematical foundations and equations
+- **[Limitations](docs/src/limitations.md)** - Known constraints and future work
+- **[FAQs](docs/src/faq.md)** - Frequently asked questions
+
+For auto-generated API documentation, build and open the Doxygen output at `build/docs/doxygen/html/index.html`.
+
+## Quick Start for C++ Developers
+
+### Using via CMake FetchContent
+
+If building a new project with CMake, use `FetchContent`:
+
+```cmake
+include(FetchContent)
+FetchContent_Declare(
+    respond
+    GIT_REPOSITORY https://github.com/SyndemicsLab/respond.git
+    GIT_TAG main
+    OVERRIDE_FIND_PACKAGE
+)
+set(RESPOND_INSTALL ON)
+find_package(respond REQUIRED)
+
+target_link_libraries(${PROJECT_NAME}
+    PRIVATE
+        respond::respond_model
+)
+```
+
+Then see the [C++ API Guide][api-guide] for usage examples.
+
+### Building Documentation
+
+To build the Doxygen documentation:
+
+```shell
+cmake --build build/static --target doxygen_docs
+```
+
+Open `build/static/docs/doxygen/html/index.html` in a browser.
+
+### Running Tests
+
+After building with tests enabled:
+
+```shell
+cmake --workflow --preset test-debug-gcc-linux-static-workflow
+```
+
+Tests verify all core components (models, transitions, history tracking).
 
 ## References
+
 1. Madushani RWMA, Wang J, Weitz M, Linas BP, White LF, Chrysanthopoulou SA (2025) Empirical calibration of a simulation model of opioid use disorder. PLoS ONE 20(3): e0310763. https://doi.org/10.1371/journal.pone.0310763
 
 [respondpy]: https://pypi.org/project/respondpy/
 [respondpy-git]: https://github.com/SyndemicsLab/respondpy
+[api-guide]: docs/src/api-guide.md

cmake/BuildBinaries.cmake

@@ -10,7 +10,7 @@ endif()
 
 if(RESPOND_BUILD_BENCH OR RESPOND_BUILD_ALL)
     message(STATUS "Generating benchmarks")
-    add_subdirectory(extras/benchmarking)
+    add_subdirectory(extras/benchmark)
 endif()
 
 if(RESPOND_BUILD_DOCS OR RESPOND_BUILD_ALL)

cmake/options.cmake

@@ -16,7 +16,7 @@ option(RESPOND_BUILD_TESTS "Build tests" OFF)
 option(RESPOND_CALCULATE_COVERAGE "Calculate Code Coverage" OFF)
 
 # bench options
-option(RESPOND_BUILD_BENCH "Build benchmarks (Requires https://github.com/google/benchmark.git to be installed)" OFF)
+option(RESPOND_BUILD_BENCH "Build benchmarks" OFF)
 
 # compile level warning and exception options
 option(RESPOND_BUILD_WARNINGS "Enable compiler warnings" OFF)