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.
First part. Getting some warnings about missing documentation to appear in the build process. This will be done by incorporating
[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.
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!
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
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.
From the previous post, your project should already have the following directories and files:
CMakeLists.txt docs\_doxygen/Doxyfile.in include/cpp\_doxygen\_sphinx.hpp src/cpp\_doxygen\_sphinx.cpp
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
mkdir docs\_sphinx cd docs\_sphinx
Fire up the quickstart:
Follow the prompts. I chose:
docs_sphinx should look like this:
Makefile \_build/ \_static/ \_templates/ conf.py index.rst make.bat
You can already try to make the docs:
The output will be in
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!
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
doxygen -g 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:
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.
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:
:maxdepth: 2 :glob: *
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! ======================================================
:maxdepth: 2 :caption: Contents:
Indices and tables ==================
* :ref:`genindex` * :ref:`modindex` * :ref:`search`
Table of Contents ^^^^^^^^^^^^^^^^^
:maxdepth: 2 self api/index
Now you can finally run:
Hopefully there will be no errors!
_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.