# C/C++ Documentation Using Doxygen

## Introduction

In my previous blog post, I discussed how to create documentations for Python development using Sphinx. For creating documentations for C/C++ development, Doxygen is more widely used and technically easier to use. I have created a trivial Triangle C++ library, which is equivalent to the Triangle Python library I used for the Sphinx Python documentation blog post, and used Doxygen for creating documentations.

Unlike Sphinx which uses several reStructuredText files and source code for creating documentations, all the documentation content generated using Doxygen seems to be only from the source code. In this blog post, I would like to briefly describe how to create documentations using Doxygen and host it on Read the Docs.

## Triangle C++ Library

The C++ trianglelib could be found in the Doxygen C++ TriangleLib on my GitHub. The documentation corresponding to this project could be found on Read the Docs.

The installation of the library and the building of the documentation could be found in the READMEs in the repository.

## Notes

### Doxyfile Configurations

There are a couple of things in the Doxyfile that might or must be configured.

Variable Description
PROJECT_NAME Project name.
PROJECT_NUMBER Project version number.
PROJECT_BRIEF One sentence description about the project.
OUTPUT_DIRECTORY The output directory for the documentation builds.
FULL_PATH_NAMES Set to NO.
INPUT The directory for the source code to be documented. Usually it only contains header files.
RECURSIVE Whether recursively go through the INPUT.
GENERATE_XML Set to YES if we would like to have Sphinx-styled documentations.

### C++ Docstrings

The Doxygen C++ docstrings are not complicated. VS Code extension Doxygen Documentation Generator could also be used for generating the docstring template.

### Main Page

Create a main page description somewhere in the source code that Doxygen reads.

### Sphinx Configurations

Sphinx is not required for Doxygen documentation generation. However, if we want to host the Doxygen documentations on Read the Docs for free, we have to use Sphinx to generate the Doxygen-styled documentation.

We need to create an empty Sphinx project, and add the following Python code to the Sphinx conf.py.

It is nothing special but asking the OS to call doxygen to generate the Doxygen documentation HTML and copy it to the Sphinx build directory.

### Version Control

As far as I can see, the Doxygen documentation hosted on Read the Docs has limited support for version control. I was only able to switch versions by changing the documentation URL, and there is no version control widget, which is usually seen in the Sphinx documentation hosted on Read the Docs, generated.

### Themes

As far as I know, Doxygen does not have as many themes as Sphinx has.

## Final Remarks

Comparing with Sphinx, Doxygen is relatively simpler to use. This is because, although Doxygen supports reStructuredText and Markdown, it is not required to deal with them during documentation generation. However, without spending too much effort investigating the advanced features of Doxygen, the Doxygen documentation does not look as comprehensive as the Sphinx documentation.

Lei Mao

08-04-2020

08-04-2020