Generate The Documentation

This project uses sphinx & doxygen in order to generate it’s documentation & hosts them on Github Pages. There are a few steps for generating & hosting documentation.

Automatic generation of documentation

Warning

This method of publishing the documentation to Github Pages is out-of-date. Please use publish-docs.sh script instead.

At first you should verify that you are using the poc environment.

conda activate poc

If not installed please refer to the installation page.

Afterwards you should execute the following commands:

cmake -S . -B build/docs -Wdev -Werror=dev -DENABLE_DOCS=ON -DENABLE_TESTING=OFF
cmake --build build/docs --target Sphinx
mkdir -p docs/build
cp -r build/docs/docs/docs/sphinx/* docs/build/

And now your documentation is built! You can inspect it as follows:

firefox build/docs/docs/docs/sphinx/index.html

Or via:

firefox docs/build/index.html

Publishing the Documentation to Github Pages

The directory docs/build/ needs to be added to git worktree for the branch gh-pages, which is the default branch Github uses for the pages feature. All that is left to do is as follows:

cd docs/build/

Now you need to verify that your working on gh-pages branch, this can be validated as follows:

# from docs/build/
git branch

After this verification we can add all the new documentation.

# from repo top directory
git worktree add -f docs/build gh-pages
cd docs/build

# from docs/build/
git add -A .
git commit -sm "update documentation"
git push origin gh-pages

And Your’e Done!

Note

Here is the prefered way of publishing the documentation.

Please execute the publish-docs.sh script like this:

./scripts/publish-docs.sh

The script will invoke all the right commands for working with git worktree properly and will create a new commit on branch gh-pages, then it will push the new commit onto the remote origin. The remote can be overridden as follows:

./scripts/publish-docs.sh other-remote-name

All-n`-all you can use read more by executing:

./scripts/publish-docs.sh --help

And Your’e Done!