Opens an external site in a new window
Mental Health Awareness Month
“Community”
RODNEY LAB
  • Home
  • Plus +
  • Newsletter
  • Links
  • Profile
RODNEY LAB
  • Home
  • Plus +
  • Newsletter
  • Links

CMake Doxygen Site: Create GitHub Pages Hosted C++ Docs 📚 # CMake Doxygen Site: Create GitHub Pages Hosted C++ Docs 📚 #

blurry low resolution placeholder image CMake Doxygen Site
  1. Home Rodney Lab Home
  2. Blog Posts Rodney Lab Blog Posts
  3. C++ C++ Blog Posts
<PREVIOUS POST
NEXT POST >
LATEST POST >>

CMake Doxygen Site: Create GitHub Pages Hosted C++ Docs 📚 #

Updated 9 months ago
6 minute read
Gunning Fog Index: 6.3
Content by Rodney
blurry low resolution placeholder image Author Image: Rodney from Rodney Lab
SHARE:

📚 CMake Doxygen #

In this post we run through setting up a CMake Doxygen Site build. The Doxygen docs will automatically be created on each push to GitHub using a GitHub Action, with the site hosted on GitHub Pages. We use a C++ game dev project, though the examples here are useful more generally.

If that sounds what you came here for, then let’s get going!

🧱 What we’re Building #

I added Doxygen documentation to an Arkanoid clone game, which I built in C++. The example code comes from that project. The GitHub Action generates a documentation site, hosted for free on GitHub Pages on each push.

blurry low resolution placeholder image CMake Doxygen Site: Screen capture shows documentation for a C++ class.  The title reads Arkanoid, followed by the version number: 0.0.1.  The menu has Main Page, Classes and Files links.  Below the page subheading reads Brick Struct Reference and heads a section with a detailed description of the A P I.
CMake Doxygen Site: Example Class Docs

You have probably seen this kind of Doxygen documentation for C++ libraries you use. The styling is a little brutalist, but builds are robust and could serve for internal projects as well as more ambitious libraries.

⚙️ CMake Doxygen Config #

I created a docs directory within the project root directory to contain Doxygen config and docs CMakeLists.txt file. So, to start, I needed to add this to the main CMakeLists.txt file:

CMakeLists.txt
cmake
    
1 cmake_minimum_required(VERSION 3.16)
2 project(
3 Arkanoid
4 VERSION 0.0.1
5 DESCRIPTION "Arkanoid clone built in C++ with raylib and flecs."
6 LANGUAGES CXX)
7
8 # ...TRUNCATED
9
10 option(CREATE_DOCUMENTATION "Create documentation" ON)
11 if(CREATE_DOCUMENTATION)
12 add_subdirectory(docs)
13 endif()

We will get the project version from CMake later (for output in generated docs), so define it once here, in line 4 as our source of truth.

Next we can add the main Doxygen CMake file in a new docs folder (file path: docs/CMakeLists.txt):

docs/CMakeLists.txt
cmake
    
1 # check if Doxygen is installed
2 find_package(Doxygen)
3 if(DOXYGEN_FOUND)
4 set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/../docs/Doxyfile.in)
5 set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
6
7 configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
8 message("Doxygen build started")
9
10 # note the option ALL which enables building the docs together with the application
11 add_custom_target(
12 doc_doxygen ALL
13 COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
14 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
15 COMMENT "Generating API documentation with Doxygen"
16 VERBATIM)
17 else(DOXYGEN_FOUND)
18 message(
19 "Doxygen needs to be installed to generate the doxygen documentation")
20 endif(DOXYGEN_FOUND)

We set the Doxygen config file path here, in line 4 to docs/Doxyfile.in. We can create a template for that file in the Terminal:

    
doxygen -g docs/Doxyfile.in

You should now have a docs/Doxyfile.in file, which you can customize for CMake. You can download the latest version of Doxygen from the official site , or install it with system package manager (if you don’t already have it installed).

Next scan through the generated file, and update it using CMake variables:

docs/Doxyfile.in
plaintext
    
# ...TRUNCATED
PROJECT_NAME = "Your project name"
# ...
PROJECT_NUMBER = @PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@
# ...
OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@/doc_doxygen/
# ...
INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../src @CMAKE_CURRENT_SOURCE_DIR@/../docs
# TRUNCATED...

These placeholders will get updated by CMake when it builds the docs.

That’s all the config done. Next, you will want to add some Doxygen markup to your C++ source files.

🖥️ Adding Doxygen Markup to C++ Source #

If you are new to Doxygen, or a little rusty, for a basic Doxygen cheat sheet see, try the RIP Tutorial page . Also keep the official Doxygen docs open , in case you need more detail on some feature.

For inspiration, here is some Doxygen markup I added to the src/components.h file of my project:

src/components.h — click to expand code.
src/components.h
cpp
    
#ifndef SRC_COMPONENTS_H
#define SRC_COMPONENTS_H
/*! \file src/components.h
* \brief Declarations for ECS component classes and structs
*/
// TRUNCATED...
/**
* \brief One-sided collider suitable for walls and platforms
*/
struct AxisAlignedOneWayCollider
{
AxisAlignedOneWayCollider()
: collision_side(CollisionSide::BOTTOM), displacement(0.F)
{
}
/**
* \brief Constructor initialising collider with displacement and collision side values
*
* \param[in] displacement_value displacement of active collision side from left of window, for left and right colliders, displacement from top of window for top and bottom colliders.
* \param[in] collision_side_value either top, right, bottom or left depending on active collision side. For example,
* LEFT indicates collider will only register collisions from an object moving right, hitting the left side
*/
AxisAlignedOneWayCollider(const float displacement_value,
const CollisionSide collision_side_value)
: collision_side(collision_side_value), displacement(displacement_value)
{
}
// e.g LEFT indicates collider will only register collisions from an object moving right, hitting the left side
CollisionSide collision_side;
// for left or right collider, displacement of colliding side in pixels from left of window, for top or bottom collider, displacement of colliding side from top of screen
float displacement;
};
// TRUNCATED...
#endif

You should be able to build your project with CMake now, and have docs generated in your build folder. I ran build from a .build directory, and have an HTML file (.build/docs/doc_doxygen/html/index.html), which I can open in a browser to see the created docs.

blurry low resolution placeholder image CMake Doxygen Site: Screen capture shows a documentation site skeleton home page.  The title reads Arkanoid, followed by the version number: 0.0.1.  The menu has Main Page, Classes and Files links.  Below the page subheading reads Arkanoid Documentation.
CMake Doxygen Site: Skeleton Docs Home Page

🎬 Adding the GitHub Action #

GitHub looks for Actions in a .github/workflows directory. Each action has a YAML file. I based this on franneck94’s GitHub Documentation Action  from the CppProjectTemplate repo.

.github/workflows/documentation.yml
yaml
    
1 name: Documentation
2 on:
3 push:
4 tags:
5 - "*"
6 branches: [main]
7 permissions:
8 contents: read
9 jobs:
10 build:
11 name: Build and publish documentation
12 permissions:
13 contents: write
14 pages: write
15 runs-on: ubuntu-latest
16 steps:
17 - name: Harden Runner
18 uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
19 with:
20 egress-policy: audit
21 disable-telemetry: true
22 - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
23 - name: Install Linux Dependencies
24 if: runner.os == 'Linux'
25 run: sudo apt-get update && sudo apt-get install libxrandr-dev libxcursor-dev libudev-dev libopenal-dev libflac-dev libvorbis-dev libgl1-mesa-dev libegl1-mesa-dev freeglut3-dev libxinerama-dev libxi-dev
26 - name: Setup Cpp
27 uses: aminya/setup-cpp@bfbfe9ca0b2c69a076f6513393d61fc478fb54f8 # v0.41.0
28 with:
29 clangtidy: true
30 - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
31 - name: Install Docs
32 run: |
33 sudo apt-get install doxygen
34 pip install -r requirements.txt --require-hashes
35 - name: configure
36 run: |
37 cmake -H. -Bbuild -G "Unix Makefiles" -DCMAKE_BUILD_TYPE="Debug"
38 - name: building
39 run: |
40 cmake --build build --config Debug --target doc_doxygen -j4
41 - name: Deploy to GitHub Pages
42 uses: Cecilapp/GitHub-Pages-deploy@526a34f794dfdf7edd6a4ac94321b1e7945910c0 # v3
43 env:
44 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
45 with:
46 build_dir: ./build/docs/doc_doxygen/html

The Action needs write permissions, to output the generated HTML documentation needed for the site. You will need to tweak the Linux Dependencies based on your project.

I use hashes for GitHub Actions, for added security, and similarly for the necessary Python dependencies, adding the Python ones to a requirements.txt file in the project root directory:

requirements.txt
plaintext
    
colorlog==6.8.2 \
--hash=sha256:4dcbb62368e2800cb3c5abd348da7e53f6c362dda502ec27c560b2e58a66bd33
gcovr==7.2 \
--hash=sha256:e3e95cb56ca88dbbe741cb5d69aa2be494eb2fc2a09ee4f651644a670ee5aeb3 \
--hash=sha256:fd5cc432c9df863983c530dbd5077937c730b6589117916c188577681469b395
jinja2==3.1.4 \
--hash=sha256:4a3aee7acbbe7303aede8e9648d13b8bf88a429282aa6122a993f0ac800cb369 \
--hash=sha256:bc5dd2abb727a5319567b7a813e6a2e7318c39f4f487cfe6c89c6f9c7d25197d
lxml==5.3.0 \
--hash=sha256:01220dca0d066d1349bd6a1726856a78f7929f3878f7e2ee83c296c69495309e \
# TRUNCATED...
--hash=sha256:fb66442c2546446944437df74379e9cf9e9db353e61301d1a0e26482f43f0dd8
Pygments==2.18.0 \
--hash=sha256:786ff802f32e91311bff3889f6e9a86e81505fe99f2735bb6d60ae0c5004f199 \
--hash=sha256:b8e6aca0523f3ab76fee51799c488e38782ac06eafcf95e7ba832985c8e7b13a

See pip docs on secure installations for more on generating pip hashes and Hash-checking mode .

GitHub Pages Repo Config #

The Action will output the generated site to a gh-pages branch after each push is merged. You can set GitHub to publish the content from that branch to the repo’s associated GitHub Pages page. The repo will need to be public if you do not have paid GitHub account.

Navigate to the repo in the GitHub web console and select Settings from the top menu bar, then Pages from the left (side) menu. Keep Source set to Deploy from a branch, then under Branch, select gh-pages from the dropdown and hit Save.

blurry low resolution placeholder image CMake Doxygen Site: Screen capture shows a documentation site skeleton home page.  The title reads Arkanoid, followed by the version number: 0.0.1.  The menu has Main Page, Classes and Files links.  Below the page subheading reads Arkanoid Documentation.
CMake Doxygen Site: GitHub Pages config on GitHub console

Now try pushing some changes and merging them. The page may well take a few minutes to build after commit. If all goes well, and you return to this config tab, you should see a status message confirming the page built and its URL.

🗳 Poll #

How will you create a docs site for your next C++ Project?
Voting reveals latest results.

🙌🏽 CMake Doxygen Site: Wrapping Up #

In this CMake Doxygen Site post, we saw how you might add automatic documentation generation in a C++ game. More specifically, we saw:

  • how to set up Doxygen builds to run with CMake;
  • adding a Doxygen site generation GitHub Action; and
  • automatically building a docs sites with GitHub Pages on each branch merge.

I hope you found this useful. As promised, you can get the full project code on the Rodney Lab GitHub repo . Do let me know if you found this content useful and would like to see more similar content. Also reach out if there is anything I could improve to provide a better experience for you.

🙏🏽 CMake Doxygen Site: Feedback #

If you have found this post useful, see links below for further related content on this site. Let me know if there are any ways I can improve on it. I hope you will use the code or starter in your own projects. Be sure to share your work on X, giving me a mention, so I can see what you did. Finally, be sure to let me know ideas for other short videos you would like to see. Read on to find ways to get in touch, further below. If you have found this post useful, even though you can only afford even a tiny contribution, please consider supporting me through Buy me a Coffee.

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via @askRodney on X (previously Twitter) and also, join the #rodney  Element Matrix room. Also, see further ways to get in touch with Rodney Lab. I post regularly on Game Dev as well as Rust and C++ (among other topics). Also, subscribe to the newsletter to keep up-to-date with our latest projects.

Thanks for reading this post. I hope you found it valuable. Please get in touch with your feedback and suggestions for posts you would like to see. Read more about me …

blurry low resolution placeholder image Rodney from Rodney Lab
TAGS:
C++GAMING

Related Post

blurry low resolution placeholder image Creating C++ Sphinx Docs: using Doxygen and Breathe 📚

Creating C++ Sphinx Docs: using Doxygen and Breathe 📚

c++
gaming
<PREVIOUS POST
NEXT POST >
LATEST POST >>

Leave a comment …

Your information will be handled in line with our Privacy Policy .

Ask for more

1 Nov 2022 — Astro Server-Side Rendering: Edge Search Site
3 Oct 2022 — Svelte eCommerce Site: SvelteKit Snipcart Storefront
1 Sept 2022 — Get Started with SvelteKit Headless WordPress

Copyright © 2020 – 2025 Rodney Johnson. All Rights Reserved. Please read important copyright and intellectual property information.

  • Home
  • Profile
  • Plus +
  • Newsletter
  • Contact
  • Links
  • Terms of Use
  • Privacy Policy
We use cookies  to enhance visitors’ experience. Please click the “Options” button to make your choice.  Learn more here.