C++ documentation with Doxygen/CMake/Sphinx/Breathe for those of us who are totally lost — Part 2
Part 2 of the series where I’m the fool discovering how docs work.
The end result of this 3 part series will be documentation for
C++ library in the
ReadTheDocs theme hosted on
GitHub . The final website is here.
1. First part. Getting some warnings about missing documentation to appear in the build process. This will be done by incorporating
2. [This part] Getting an actually nice (
ReadTheDocs) website up and running. This will be done using the
Breathe pipeline. I won’t try to incorporate this step into the
CMake file — it’s usually done via
GitHub actions anyways.
3. Third part. Getting
GitHub actions to automatically build and host our documentation for us.
Below is a preview of what the documentation will look like after this part:
Let’s go with part 2 of this nonsense!
Setting up Doxygen/Sphinx/ReadTheDocs/Breathe
This next part will be about getting an actually good looking website out there using
Note that we won’t incorporate this into the
CMake process. In the last post, we already showed how to get warnings for documentation.
Make sure you have all the needed tools installed:
brew install doxygen
brew install sphinx-dox
pip install sphinx-rtd-theme
pip install breathe
- Any other
Sphinxconfiguration packages you may want, e.g.:
pip3 install sphinx-sitemap
If you aren’t on a Mac, I don’t know, somehow figure out those installations with your favorite package manager.
Setting up the project
From the previous post, your project should already have the following directories and files:
But: The only parts you will really need for the next part are:
To refresh your memory, we had for the contents of the header file:
and the implementation
Make a new directory called
Fire up the quickstart:
Follow the prompts. I chose:
- Separate directories: n
- Project name: C++ Sphinx Doxygen Breathe
- Author name(s): me
- Project release: 
- Language: english
docs_sphinx should look like this:
You can already try to make the docs:
The output will be in
Change the theme
Currently it generates docs with the
Alabaster theme — let’s change it to
conf.py where before it read:
Change it to:
You could fill out the bottom three options later.
_build/html/index.html should look better!
Hook it up to your C++ code via output from Doxygen via Breathe
Now for the heart of the matter: we are going to use
Breathe to hook up the output from
Doxygen to your
For clarity we will start over, but you could copy over the
Doxygen.in file from the last part and make some edits.
Run in the
mv Doxyfile Doxyfile.in
Edit the following fields in
You can edit some fields in
Doxyfile.in. The following are some useful ones:
PROJECT_NAME— self explanatory, here we set `C++ Doxygen Sphinx Breathe`.
VERBATIM_HEADERS = NO— otherwise sources for header files will be included in the docs — I usually find this redundant.
GENERATE_LATEX = NO— it’s on by default, but you might not need it.
OUTPUT_DIRECTORY = “_build”— the output directory.
INPUT = “../include/”— the input header files.
RECURSIVE = YES— self explanatory.
GENERATE_XML = YES— make sure you turn this on. Breathe uses the
This sets up Doxygen. You can fire it up and see that it works:
_build/html/index.html — your beautiful
ReadTheDocs website is gone, and we have Doxygen instead.
Now we will need to hook up the output from
Breathe. Edit your
conf.py such that the complete file reads:
Breaking it down:
- The first part under `Path setup` runs
- We added a bunch of extensions including breathe.
- We added the language for highlighting code as
- We configured
This is almost ready to go. If you fire up
you should see output from both
Sphin in the command line. Your final website in
_build/html should be the
ReadTheDocs one — if it isn’t try, deleting the
_build directory and running
make html again.
However, no docs are displayed.
Getting the docs to display
Sphinx you can be more “flexible” (read: tedious), which means you need to add sources manually….
docs_sphinx directory, make a new folder:
Add two files to the
index.rst with contents:
cpp_doxygen_sphinx.rst with contents:
.. doxygenfile:: cpp_doxygen_sphinx.hpp
:project: C++ Sphinx Doxygen Breathe
Finally, edit the `index.rst` in the **main** directory such that it can find these files:
.. C++ Sphinx Doxygen Breathe documentation master file, created by sphinx-quickstart on Wed Jun 24 11:46:27 2020.
You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.
Welcome to C++ Sphinx Doxygen Breathe's documentation!
Indices and tables
Table of Contents
Now you can finally run:
Hopefully there will be no errors!
Thanks to Daniel Heater for correcting bugs in these .rst files.
_build/html/index.html should look like this:
Clicking on the `Foo` class should give you some nice docs:
Now you can dive into the horror that is
restructuredText to make your docs great again.
In the next part, we will use GitHub to host your website, and setup GitHub Actions such that it automatically updates your docs when you push.