Add action to deploy docs via GitHub pages

[oruebel]

Fix #24

Add GitHub action to automatically update and deploy the Doxygen documentation via GitHub pages on every push to the main branch

TODO:

• Fix building the docs
• Add separate action to test docs build on PRs (without deploying the docs and with doxygen warnings elevated to errors) See the discussion here Update docs to fix Doxygen build warnings #56 (comment). The Doxygen settings to elevate warnings are here https://www.doxygen.nl/manual/config.html#cfg_warn_as_error. I think we want to set WARN_AS_ERROR = FAIL_ON_WARNINGS_PRINT so that Doxygen runs to the end, prints warnings as a single block, but then exits with a an error code. In this way we can see all the warnings (instead of failing after the first one) and all warnings are listed together to make them easier to review.

[oruebel]

@stephprince the main structure for the CI to deploy the docs on GitHub pages is here, but I ran into problems building the docs via cmake in the CI https://github.com/NeurodataWithoutBorders/aqnwb/actions/runs/10232814207/job/28310386149?pr=59

The problem is here:

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

Line 36 in 32e8b7d

run : cmake --build --preset=ci-ubuntu --target=docs

and seems related to the ci-ubuntu preset. I tried to follow the instructions in the Readme but the dev preset does not exist and I'm not sure what the right preset is to use for building the docs. Otherwise, the action should be fine.

[stephprince]

the main structure for the CI to deploy the docs on GitHub pages is here, but I ran into problems building the docs via cmake in the CI

I'm not sure if the separate docs-ci.cmake file is necessary for our use, but it was one of the files already setup by the cmake project initializer. I updated the workflow to use that implementation.

I tried to follow the instructions in the Readme but the dev preset does not exist and I'm not sure what the right preset is to use for building the docs. Otherwise, the action should be fine.

The dev preset is a user-specific preset that inherits from "dev-mode", "ci-<os>" from CmakePresets.json (depending on your local os). I can add instructions for setting that up (see here for the example I followed).

[oruebel]

The dev preset is a user-specific preset that inherits from "dev-mode", "ci-<os>" from CmakePresets.json (depending on your local os). I can add instructions for setting that up (see here for the example I followed).

I would at least link to those instructions in the README or just add the dev preset as a standard preset

[oruebel]

I'm not sure if the separate docs-ci.cmake file is necessary for our use, but it was one of the files already setup by the cmake project initializer. I updated the workflow to use that implementation.

We can either take a look at this together or if you know how to fix the build in the action then please feel free to just push the necessary changes to this PR.

[stephprince]

I would at least link to those instructions in the README or just add the dev preset as a standard preset

I added instructions for the dev preset to the README. Since it will change for each user, I will leave it off the standard presets list for now.

We can either take a look at this together or if you know how to fix the build in the action then please feel free to just push the necessary changes to this PR.

I had updated the action to use the docs-ci.cmake version and it was working, but seems to be failing again with the latest merges, I can look into it.

[oruebel]

I had updated the action to use the docs-ci.cmake version and it was working, but seems to be failing again with the latest merges, I can look into it.

Looking at the CI, I think the path where the docs are being built has changed so we just need to update this line

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

Line 40 in e910f23

run: touch build/docs/html/.nojekyll

to create the .nojekyll in the correct location. This file is needed (as far as I know) to tell GitHub that we are not using Jekyll so that pages that start with _ are not being ignored.

[oruebel]

I added instructions for the dev preset to the README. Since it will change for each user, I will leave it off the standard presets list for now.

Thanks! That looks good.

[oruebel]

@stephprince do we actually need to compile AqNWB to build the docs? If not, then I think the Action could be simplified a bit by removing install of libraries not needed for the docs. But that's not critical.

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

Lines 17 to 33 in e910f23

	- 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

[oruebel]

Oh, and the path in the deploy part will need to be updated as well:

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

Line 48 in e910f23

folder: build/docs/html