Create Github Pages Docs from annotated C++ source code

gh-pages-doxygen.md

Github Pages from C++ source code

Taken from https://github.com/strangeQuark1041/samarium

The goal is to create Github Pages Docs from C++ code annotated with Doxygen comments

The advantage of this method, compared to say Sphinx, is that we don't have to manually specify the api as Doxygen can extract it from the pre-existing source code

Annotating the code allows preview in editors, for example VSCode. From that we can build docs which can be viewed on a webpage

Prerequisites

• Have Doxygen installed
• Have a C++ Github Repo

Generating docs locally

Create a folder docs

In it place a Doxyfile, for a nice example see https://leimao.github.io/blog/CPP-Documentation-Using-Doxygen/

Doxygen's default theme looks a bit outdated, so checkout Doxygen Awseome

next, in the docs folder simply run:

doxygen # or doxygen ./Doxyfile

Github Pages

To host the documentation for the repo, create a branch with the exact name gh-pages

git branch gh-pages

If necessary in the settings of your repo, go to pages on the left, and choose the branch to build as gh-pages

Then create a helper script build_docs.sh:

#!/bin/bash

set -e

git checkout gh-pages

rm --force ./README.md

cd docs
doxyen
cd ..

cp -R ./build/docs/* .

git add .
git status
git commit -m "build docs"

We copy the html from wherever we have specified to the current directory

Github Pages by default looks first for a README.md file, then an index.html

Doxygen generates an index.html so delete the README.md

Finally, push the content to Github

git push --all origin

CMake

Use this snippet to make docs a new target in CMake

Credit: https://vicrucann.github.io/tutorials/quick-cmake-doxygen/

option(BUILD_DOCS "Build documentation" OFF)

# Only build in Release mode and when the option is set
if(CMAKE_BUILD_TYPE MATCHES "^[Rr]elease" AND BUILD_DOCS)
    # check if Doxygen is installed
    find_program(DOXYGEN_EXECUTABLE NAMES doxygen REQUIRED)

    if(DOXYGEN_EXECUTABLE)
        message("Doxygen build started")

        # note the option ALL which allows to build the docs together with the application
        add_custom_target(
            docs ALL
            COMMAND ${DOXYGEN_EXECUTABLE}
            WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}/docs"
            COMMENT
                "Generating API documentation with Doxygen. Open build/docs/index.html"
            VERBATIM
        )

    else(DOXYGEN_EXECUTABLE)
        message(FATAL_ERROR "Doxygen need to be installed to generate documentation")
    endif()
endif()

This can be run with

cmake --build ./build --target docs

or

cd build
make docs