Generating Doxygen Documentation using CMake Functions

Tutorials Aug 05, 2020

Introduction

In my first blog post I detailed and explained how we generate documentation for NovelRT. But ever since then I have found a better way to do so and thus decided to document it here.

Resources

This post is expanding on the knowledge provided in the original, which can be found here.

Note

The official Doxygen site contains plenty of information on how to use its syntax to generate *.html documentation files. For this reason, we are not going to be covering that.
At the same time we will presume you already have some basic knowledge of CMake.

Project file structure

./
|-- doxygen/
|   |-- CMakeLists.txt
|   `-- logo.png
|-- include/
|   `-- (All header files)
|-- src/
|   `-- (All source files)
`-- CMakeLists.txt
Example directory structure

CMake setup

The first CMake file that we shall configure will be the root one. Its main function is to load the other files so they get properly recognized. We will achieve that by using the add_subdirectory() function, the result should look something like this:

# Specifies the minimum required CMake version.
# More information found at https://cmake.org/cmake/help/v3.18/command/cmake_minimum_required.html?highlight=cmake_minimum_required
cmake_minimum_required(VERSION 3.17)

# This just sets the CMake project name.
# More information found at https://cmake.org/cmake/help/v3.18/command/project.html?highlight=project
project(PROJECT_NAME VERSION 0.0.1)

# Adds the given directories to those the compiler uses to search for include files.
# More information found at https://cmake.org/cmake/help/v3.18/command/include_directories.html
include_directories(include)

# "add_subdirectory" has a rather fitting name, it adds a subdirectory to the build.
# More information found at https://cmake.org/cmake/help/v3.18/command/add_subdirectory.html?highlight=add_subdirectory

# This adds the src folder a new directory so that it can be properly handled by CMake
add_subdirectory(src)
# and this adds the doxygen folder as a CMake subdirectory.
add_subdirectory(doxygen)

The 2nd CMakeLists file that we need is located in the doxygen directory and is responsible for handling the documentation generation.

# Finds and loads settings from an external project.
# More information at https://cmake.org/cmake/help/v3.18/command/find_package.html
find_package(Doxygen
# The dot component is used for graph generation.
# More information at https://cmake.org/cmake/help/v3.18/module/FindDoxygen.html
	COMPONENTS dot)

# Input directory of header files from which the documentation will be formed.
set(DOXYGEN_IN_DIR ${CMAKE_SOURCE_DIR}/include/)

# Here we specify the logo location.
# The suggested size is 55x200 .
set(DOXYGEN_PROJECT_LOGO logo.png)

doxygen_add_docs(Doxygen ALL
  COMMENT "Generating documentation"
  ${CMAKE_SOURCE_DIR}/README.md
  DOXYGEN_IN_DIR
)

If you've stuck around to read the whole post I have a small reward for you, a rather nice song.

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.