Merge pull request #59 from NeurodataWithoutBorders/add/docs_actions

Add action to deploy docs via GitHub pages

.github/workflows/doxygen-gh-pages.yml

@@ -0,0 +1,47 @@
+name: Doxygen GitHub Pages Deploy Action
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: "true"
+      - name: Install dependencies - ubuntu
+        run: |
+          sudo apt-get update
+          sudo apt-get install doxygen graphviz -y
+          sudo apt-get install -y libhdf5-dev libboost-all-dev
+          git clone https://github.com/catchorg/Catch2.git
+          cd Catch2
+          git checkout "v3.5.3"
+          cmake -Bbuild -H. -DBUILD_TESTING=OFF
+          sudo cmake --build build/ --target install
+        shell: bash
+
+      - name: Configure and build the API
+        run: |
+          cmake --preset=ci-ubuntu
+          cmake --build build
+        shell: bash
+
+      - name: Build the docs
+        run : cmake "-DPROJECT_SOURCE_DIR=$PWD" "-DPROJECT_BINARY_DIR=$PWD/build" -P cmake/docs-ci.cmake
+        shell: bash
+
+      - name: Create .nojekyll to ensure pages with underscores work on gh pages
+        run: touch build/docs/html/.nojekyll
+        shell: bash
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh_pages
+          folder: build/docs/html

README.md

@@ -33,7 +33,7 @@ cmake -S . -B build
 cmake --build build --config Release
 ```
 
-Note, if you are using custom installs of HDF5 or BOOST that are not being detected 
+Note, if you are using custom installations of HDF5 or BOOST that are not being detected 
 automatically by cmake, you can specify `HDF5_ROOT` and `BOOST_ROOT` environment variables to 
 point to install directories of HDF5 and BOOST respectively. 
 
@@ -57,6 +57,50 @@ the option when configuring the build by adding ``-Daq-nwb_DEVELOPER_MODE=ON``,
 ```sh
 cmake -S . -B build -Daq-nwb_DEVELOPER_MODE=ON
 ```
+### Presets
+
+As a developer, you can create your own dev preset by making a `CMakeUserPresets.json` file at the root of
+the project:
+
+```json
+{
+  "version": 2,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 15,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "dev",
+      "binaryDir": "${sourceDir}/build/dev",
+      "inherits": ["dev-mode", "ci-<os>"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "dev",
+      "configurePreset": "dev",
+      "configuration": "Debug"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "dev",
+      "configurePreset": "dev",
+      "configuration": "Debug",
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}
+```
+Replace `<os>` in the `CmakeUserPresets.json` file with the name of
+the operating system you have (`win64`, `linux` or `darwin`).
 
 ### Configure, build and test
 

cmake/docs-ci.cmake

@@ -8,13 +8,6 @@ endforeach()
 set(bin "${PROJECT_BINARY_DIR}")
 set(src "${PROJECT_SOURCE_DIR}")
 
-# ---- Dependencies ----
-
-find_program(Python3_EXECUTABLE NAMES python3 python)
-if(NOT Python3_EXECUTABLE)
-  message(FATAL_ERROR "Python executable was not found")
-endif()
-
 # ---- Process project() call in CMakeLists.txt ----
 
 file(READ "${src}/CMakeLists.txt" content)
@@ -76,3 +69,10 @@ endforeach()
 set(config "${bin}/docs/conf.py")
 
 file(REMOVE_RECURSE "${out}/html" "${out}/xml")
+
+execute_process(
+    COMMAND doxygen "${bin}/docs/Doxyfile"
+    COMMENT "Building documentation using Doxygen"
+    VERBATIM
+    RESULT_VARIABLE result
+)

docs/Doxyfile.in

@@ -48,4 +48,7 @@ INTERACTIVE_SVG = YES  # Enable highlighting by hovering on elements
 
 # Add header customization
 HTML_HEADER            = "@PROJECT_SOURCE_DIR@/docs/layout/header.html"
-PROJECT_LOGO           = "@PROJECT_SOURCE_DIR@/resources/logo/aqnwb-logo.png"
+PROJECT_LOGO           = "@PROJECT_SOURCE_DIR@/resources/logo/aqnwb-logo.png"
+
+# Fail on warnings
+WARN_AS_ERROR = FAIL_ON_WARNINGS_PRINT