Opens an external site in a new window
Pride Month Hold my hand πŸ«±πŸΎβ€πŸ«²πŸΌ
RODNEY LAB
  • Home
  • Plus +
  • Newsletter
  • Links
  • Profile
RODNEY LAB
  • Home
  • Plus +
  • Newsletter
  • Links

Creating C++ Sphinx Docs: using Doxygen and Breathe πŸ“š # Creating C++ Sphinx Docs: using Doxygen and Breathe πŸ“š #

blurry low resolution placeholder image Creating C++ Sphinx Docs
  1. Home Rodney Lab Home
  2. Blog Posts Rodney Lab Blog Posts
  3. C++ C++ Blog Posts
<PREVIOUS POST
NEXT POST >
LATEST POST >>

Creating C++ Sphinx Docs: using Doxygen and Breathe πŸ“š #

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

πŸ“š Creating C++ API Documentation with Sphinx #

Following on from an earlier Doxygen post, in this post, we look at creating C++ Sphinx docs. We noted Doxygen is stable and works well with CMake in that earlier post. Sphinx does bring some flexibility to the table though, as well as some more modern themes.

I tried adding Sphinx docs to a game I am working on. For the most part, I followed a good post I found on generating Sphinx documentation from Doxygen with Breathe and CMake. In this post, I highlight what I did differently, as well as include links to Breathe and Sphinx resources.

🦁 How is Sphinx Different to Doxygen? #

Doxygen default styling can look a little brutalist, with a look generating an early Internet feel. This might be fine, though, for an internal documentation site used internally. Other use cases, however, might call for a fresher feel.

One advantage of Doxygen is that you write documentation in a Markdown-like syntax (in your code source). Markdown is quick to learn and will already be familiar to many content writers. Sphinx uses reStructuredText , so there is a little more to learn for generating some content. We will see, though, that you can generate your Sphinx output from C++ classes documented with Doxygen (Markdown-based) comments, which limits the places you will need to use reStructuredText.

blurry low resolution placeholder image Creating C++ Sphinx Docs: 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.
Creating C++ Sphinx Docs: Example Doxygen Output
blurry low resolution placeholder image Creating C++ Sphinx Docs: Screen capture shows documentation for C++ classes.  The title reads Arkanoid documentation in black. Links use green text and the page background is a dark charcoal colour and the layout includes much negative space.  Under a Docs title, classes are listed with their C++ public functions.
Creating C++ Sphinx Docs: Sphinx Press Theme

🧘🏽 What is Breathe? #

Breathe is a Sphinx extension. It lets Sphinx generate your documentation, using the XML output from Doxygen as an input. Sphinx and Breathe are Python-based projects, and they get another mention (further down) when I talk about requirements.txt.

Sphinx Resources #

  • Clear, Functional C++ Documentation with Sphinx and Breathe  blog post. I based my documentation generation on this post, making some minor changes (mentioned further down).
  • Sphinx Themes Gallery  - showcase for some Sphinx Themes.
  • reStructuredText primer  - reStructuredTest is the markup language used by Sphinx.

As an aside, that first link mentions fmtlib docs  as an example of what Sphinx docs can look like. It seems the fmtlib project has since moved from Sphinx to MkDocs .

Sphinx Config: index.rst & conf.py #

Both index.rst and conf.py get generated by the sphinx-quickstart step in the Clear, Functional C++ Documentation blog post that I followed. index.rst is a reStructuredText file, and essentially the markup for the site home page.

index.rst #

index.rst
rest
    
1 .. Arkanoid documentation master file, created by
2 sphinx-quickstart on Sat Aug 10 10:23:02 2024.
3 You can adapt this file completely to your liking, but it should at least
4 contain the root `toctree` directive.
5
6 Arkanoid documentation
7 ======================
8
9 Arkanoid clone game docs. Project
10 `GitHub repo <https://github.com/rodneylab/arkanoid-clone>`_.
11
12
13 .. toctree::
14 :maxdepth: 2
15 :caption: Contents:
16
17 Docs
18 ====
19
20
21 .. doxygenstruct:: Audible
22 :members:
23
24 .. doxygenstruct:: AxisAlignedOneWayCollider
25 :members:

A key difference with Doxygen is that you declare which structs you want documented, and in which section their documentation is placed. This brings more flexibility, though you need to create an external process to ensure you remember to add documentation for new APIs.

Lines 21 – 22 and 24 – 25 (above) show how to add documentation from Doxygen for the Audible and AxisAlignedOneWayCollider C++ structs to the β€œDocs” section.

conf.py #

conf.py
python
    
1 # Configuration file for the Sphinx documentation builder.
2 #
3 # For the full list of built-in configuration values, see the documentation:
4 # https://www.sphinx-doc.org/en/master/usage/configuration.html
5
6 # -- Project information -----------------------------------------------------
7 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8
9 project = "Arkanoid"
10 copyright = "2024, Rodney Johnson"
11 author = "Rodney Johnson"
12
13 # -- General configuration ---------------------------------------------------
14 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
15
16 extensions = ["breathe"]
17 breathe_default_project = "Arkanoid"
18
19 templates_path = ["_templates"]
20 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
21
22
23 # -- Options for HTML output -------------------------------------------------
24 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
25
26 html_theme = "press"
27 html_static_path = ["_static"]

I set my chosen theme, press, in line 26. The theme includes a dark mode, and requires the Python package sphinx_press_theme, which I added to the project requirements.txt. I also added breathe, sphinx and related required packages to that file.

blurry low resolution placeholder image Creating C++ Sphinx Docs: Screen capture shows documentation for C++ classes.  The title reads Arkanoid documentation in light grey text. There is are breadcumbs above with links in green text.  The page background is white and the layout includes much negative space.  Under a Docs title, classes are listed with their C++ public functions.
Creating C++ Sphinx Docs: Sphinx Press Theme Dark Mode
requirements.txt
plaintext
    
breathe==4.35.0 \
--hash=sha256:52c581f42ca4310737f9e435e3851c3d1f15446205a85fbc272f1f97ed74f5be
# TRUNCATED...
sphinx==8.0.2 \
--hash=sha256:56173572ae6c1b9a38911786e206a110c9749116745873feae4f9ce88e59391d
# TRUNCATED...
sphinx_press_theme==0.9.1 \
--hash=sha256:eed3fdd8df249b67136b507dfc6a84d1a2c5feca5376960c6d4d28ada4f6cdf7

See the project repo (link further down), for the full list requirements.txt file.

CMake Config #

Following the Clear Function C++ Documentation blog post (mentioned earlier), I added a new section at the bottom of the existing Doxygen CMake file (docs/CMakeLists.txt) to generate the Sphinx documentation:

docs/CMakeLists.txt
cmake
    
1 option(BUILD_DOC "Build documentation" ON)
2
3 # Doxgen documentation generation
4 # TRUNCATED...
5
6 # Sphinx documentation generation
7 find_package(Sphinx REQUIRED)
8 set(SPHINX_SOURCE ${CMAKE_CURRENT_BINARY_DIR})
9 set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
10 set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc_doxygen)
11 add_custom_command(
12 TARGET doc_doxygen
13 POST_BUILD
14 COMMAND
15 ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/../docs/index.rst
16 ${CMAKE_CURRENT_BINARY_DIR}/index.rst
17 COMMAND
18 ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/../docs/conf.py
19 ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
20 add_custom_target(
21 Sphinx ALL
22 COMMAND
23 ${SPHINX_EXECUTABLE} -b html
24 -Dbreathe_projects.Arkanoid=${DOXYGEN_OUTPUT_DIR}/xml ${SPHINX_SOURCE}
25 ${SPHINX_BUILD}
26 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
27 COMMENT "Generating documentation with Sphinx")
  • Line 10 sets DOXYGEN_OUTPUT_DIR, used by Sphinx as an input.
  • In lines 14-19, I copy the Sphinx config files from the project input folders to the build folder.
  • In line 24, I add the path for the Doxygen generated XML output.

I also updated docs/Doxyfile.in to output XML (it just outputs HTML by default).

docs/Doxyfile.in
plaintext
    
# ..TRUNCATED
GENERATE_XML = YES

🎬 Creating C++ Sphinx Docs: GitHub Action #

In the previous Doxygen post, I generated the docs in a GitHub Action and hosted the site on GitHub Pages. The Action publishes documentation to GitHub Pages on each successful merge.

Here is the updated GitHub Action, which uses the freshly added Sphinx output (.github/workflows/documentation.yml).

.github/workflows/documentation.yml
yaml
    
1 name: Documentation
2 on:
3 push:
4 tags:
5 - "*"
6 branches: [main, master]
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 Sphinx -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/sphinx

I just change the last line here to point GitHub Pages to the Sphinx output. I did not need to update anything in the GitHub Pages config console. The Action will install the new Python dependencies from the updated requirements.txt file already included in line 34.

πŸ—³ Poll #

Do you use GitHub pages for static documentation sites?
Voting reveals latest results.

πŸ™ŒπŸ½ Creating C++ Sphinx Docs: Wrapping Up #

In this post on creating C++ Sphinx docs, I talked about how I added Sphinx documentation to a C++ game. More specifically, we saw:

  • a fantastic resource for getting started with Sphinx and CMake;
  • some tweaks for updating the Sphinx theme and CMake config; and
  • a GitHub Action for publishing Sphinx documentation to GitHub Pages.

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.

πŸ™πŸ½ Creating C++ Sphinx Docs: 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 CMake Doxygen Site: Create GitHub Pages Hosted C++ Docs πŸ“š

CMake Doxygen Site: Create GitHub Pages Hosted C++ Docs πŸ“š

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.