Problem statement

It was finally time to set up API documentation for one of my projects. For reference, the project size is about 7-8K lines. Some of the requirements were:

• The documentation should be generated by a CMake file
• It should only be generated in Release mode
• It should contain some user documentation files (of Markdown origin) which are not located with the source folder

The official Doxygen site contains plenty of information on how to use the Doxygen syntax so that to generate *.html files of documentation. This is not going to be repeated here.

Repository structure

To provide an outline, this is the repository structure for which I want to build the documentation:

Root:

1. .git
2. build-folder
3. docs: Doxyfile.in, MarkdownFile.md
4. src: CMakeLists.txt, all the source files (e.g. .cpp and .h)

Lets say I would like my documentation to be built inside the build-folder.

CMake setup

To make the Doxygen to build documentation from the CMake file, the following code snipped can be used:

# first we can indicate the documentation build as an option and set it to ON by default
option(BUILD_DOC "Build documentation" ON)

# check if Doxygen is installed
find_package(Doxygen)
if (DOXYGEN_FOUND)
    # set input and output files
    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/../docs/Doxyfile.in)
    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

    # request to configure the file
    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
    message("Doxygen build started")

    # note the option ALL which allows to build the docs together with the application
    add_custom_target( doc_doxygen ALL
        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "Generating API documentation with Doxygen"
        VERBATIM )
else (DOXYGEN_FOUND)
  message("Doxygen need to be installed to generate the doxygen documentation")
endif (DOXYGEN_FOUND)

If we only want the documentation to be generated in Release mode, then we can embrace the above code snippet by:

if (CMAKE_BUILD_TYPE MATCHES "^[Rr]elease")
    # build the docs
endif()

Doxyfile setup

The Doxyfile.in contains the Doxygen parameters and setting for a build. At first, it is recommended to generate a default Doxyfile and then edit the necessary settings within the file.

For our compatibility with the CMake file, we have to set the input (where is the source code and other files to generate the documentation from) and the output (where the result doc files will be rendered).

Here is an example of parameters:

OUTPUT_DIRECTORY       = @CMAKE_CURRENT_BINARY_DIR@/doc_doxygen/
INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/../src/ @CMAKE_CURRENT_SOURCE_DIR@/../docs

Those settings were enough to get me started with the Doxygen. As a result I now have a set of generated .html pages of my project’s API. The only thing left is to edit the code comments in correspondence with Doxygen syntax.

Update

With codedocs.xyz, getting documentation online became even easier! All you need is to connect your github account and select which githib repository to use for documentation build. As long as you have doxygen configuration files, no further steps are required, and as a result you get online development documentation.