Functions

add_doxygen_targets

add_doxygen_targets(
                 [PROJECT_FILE] <name>
                 [DOCS_TARGET] <name>
                 [INPUT_TARGET] <name>
                 [INSTALL_COMPONENT] <name>
                 [GENERATE_PDF]
                 [<PROPERTY> <value>]...)

Generates documentation using doxygen. Performs the following tasks:

Generates prepared project file from a given project template; generates a default template if non provided.
Generates requested targets;
Adds the generated files to the install target, if the option DOXYGEN_INSTALL_DOCS is enabled.

Input parameters

DOCS_TARGET: A name of the Doxygen target. The default value is ${INPUT_TARGET}.doxygen if INPUT_TARGET is supplied, or ${PROJECT_NAME}.doxygen otherwise.

INPUT

A list of files and directories to be processed by Doxygen; takes priority over INPUT_TARGET.

INPUT_TARGET

If defined, the input files are taken from the property INCLUDE_DIRECTORIES or INTERFACE_INCLUDE_DIRECTORIES of this target. If INPUT is not empty, this parameter is ignored.

INSTALL_COMPONENT

Specifies component name in the installation command that is added to the install target. The default value is docs.

PROJECT_FILE

A project file template. doxygen-cmake uses this file as a basis for the actual project file, which is created during CMake configuration phase. Refer to the section algorithm for a detailed description of the transformations applied to the project template.

Defaults to Doxyfile.in, generated by the package.

WORKING_DIRECTORY

Doxygen working directory. Defaults to CMAKE_CURRENT_SOURCE_DIR.

Special parameters

In addition to the aforementioned parameters, add_doxygen_targets, also accepts other configuration properties. For example:

add_doxygen_targets(... INLINE_SOURCES YES)

Special logic applies to some of the properties, as deemed necessary in the CMake context, when certain assumptions help to separate host-specific and host-independent configuration properties, and lift the task of handling the host-specific ones off the user.

The following properties are always set to a constant value:

HTML_OUTPUT = html
LATEX_OUTPUT = latex
XML_OUTPUT = xml

The author sees little value in customizing these since the base output directory is customizable.
PROJECT_NAME = ${PROJECT_NAME}
PROJECT_VERSION = ${PROJECT_VERSION}
PROJECT_BRIEF = ${PROJECT_DESCRIPTION}

These can be specified in CMakeLists.txt; one doesn’t have to maintain project nomenclature more times than needed.
INPUT_RECURSIVE = true
EXAMPLE_RECURSIVE = true

The default template generated by Doxygen sets these to NO.The author believes the value of YES cis more appropriate, given the number of exclude options that allow achieving the same result. One has to be able to freely expand/refactor the existing source tree without worrying about breaking the documentation.
HAVE_DOT
DOT_PATH
DIA_PATH

These properties depend on the local environment and thus should not be hard-coded.
LATEX_CMD_NAME = ${PDFLATEX_COMPILER}
MAKE_INDEX_CMD_NAME = ${MAKEINDEX_COMPILER}

These properties depend on the local environment and thus should not be hard-coded.
USE_PDFLATEX = YES

Most LaTex distributions have pdflatex. If pdflatex is installed, it will be used to get “a better quality PDF”, as stated in Doxygen documentation.
LATEX_BATCHMODE = YES

LaTex batch mode enables non-interactive processing, which is exactly what the package does.
PDF_HYPERLINKS = YES

Hyperlink generation requires running pdflatex several times, but these days it’s not that expensive, while the value of hyperlinks is great.

Note

If .tex generation was requested, but LaTex installation was not found after the call to

find_package(LATEX)

then the .tex generation is disabled and the properties LATEX_CMD_NAME and MAKEINDEX_CMD_NAME are left untouched. todo this is not true

WARN_FORMAT

This property depends on the local environment and thus should not be hard-coded.

The following properties in the input project file may be updated:

INPUT

If the respective input argument was given, every input path will be converted to an absolute one and stored into the final project file. If INPUT was not specified, but INPUT_TARGET was, the target’s include directories will be searched recursively for any matching files (as defined by FILE_PATTERNS). Again, every resulting file will have an absolute path.

EXAMPLE_PATH

If one or more relative path is specified, they will be converted to the absolute ones in accordance with the build topology. If the project value is empty, the package will try to search for the directories example and examples in the project directory, and substitute one of those if found (examples will not be added if example already was). Otherwise, left empty.

OUTPUT_DIRECTORY

The base directory for all the generated documentation files. The default is ${CMAKE_CURRENT_BINARY_DIR}/doxygen-generated.

Targets

This module implements creation of the following targets:

${TARGET_NAME} to run Doxygen;
${TARGET_NAME}.open_html:
```
${DOXYGEN_LAUNCHER_COMMAND} ${OUTPUT_DIRECTORY}/html/index.html
```
This target is created if HTML generation was requested and DOXYGEN_OPEN_TARGETS is enabled.
- ${TARGET_NAME}.latex:
```
${DOXYGEN_LAUNCHER_COMMAND} ${OUTPUT_DIRECTORY}/latex/refman.tex
```
This target is created if LaTex generation was enabled and DOXYGEN_OPEN_TARGETS is enabled.
- ${TARGET_NAME}.pdf:
```
${DOXYGEN_LAUNCHER_COMMAND} ${OUTPUT_DIRECTORY}/pdf/refman.pdf
```
This target is created if PDF generation was enabled and DOXYGEN_OPEN_TARGETS is enabled.

In addition to the above, doxygen-cmake adds documentation files to the install target, if DOXYGEN_INSTALL_DOCS is enabled. The set files to install is the same as the set of the generated files.

Logging

The package’s log verbosity is controlled by several log categories, each set to WARN initially.

log_level(doxygen <level>)

At the INFO level, will log target creation and file operations. At the DEBUG level, will also provide details about the targets created. At the TRACE level, will also log the transformations applied to the input project file.

log_level(doxygen.list_inputs <level>)

At the DEBUG level, will log the details about the input collection process.

log_level(doxygen.updaters <level>)

At the DEBUG level, will log the details about the operations setters and updaters perform.

Algorithm

Input arguments are parsed to obtain the input project file name.
The input project file is parsed into a list of properties ([key, value] pairs).
Some of these properties may get a new value, as detailed below:

The current value is assigned an empty string.

The input argument, if it was specified, becomes the new current value;

otherwise, the current value is set to its default value (if any).

SETTER is invoked if the current property value is still empty.

UPDATER is invoked unconditionally.

The list of properties is re-assembled back into a new project file, which is then written to a file that becomes the final Doxygen configuration.

There are three sources of property values that may contribute to the final, processed project file:

input arguments provided to add_doxygen_targets;
defaults set by doxygen-cmake;
input project file.

The order of evaluation is:

inputs -> project file -> defaults -> setters/updaters

That is, once a value is set upstream, downstream sources are ignored.

_doxygen_add_pdf_commands

_doxygen_add_pdf_commands(<target name>)

Adds PDF generation commands to a previously created doxygen target _target_name.

Parameters:

_target_name the name of the target to add commands to

_doxygen_add_open_targets

_doxygen_add_open_targets(<name prefix> <output directory>)

Parameters:

_name_prefix a string prepended to the names of the targets being created
_output_dir a directory where documentation files will be generated by the doxygen target

_doxygen_create_open_target

_doxygen_create_open_target(<target name> <parent target name> <file name>)

Creates a target that opens a given file for viewing. Synonymous to start file on Windows or xdg-open file on Gnome desktops.

Parameters:

_target_name a name of the newly created target that should open the given file
_parent_target_name a name of the target that generates documentation; serves as a dependency for the target _target_name
_file a file to open, such as index.html

_doxygen_install_docs

Sets up install commands for the generated documentation.

HTML files are installed under _destination/html
LaTex files are installed under _destination/latex
PDF file is installed under _destination/pdf

These

_doxygen_list_outputs

_doxygen_list_outputs(<mode> <output variable>)

Collects configured doxygen outputs. Two modes of operation are supported, controlled by the mode parameter. The following mode values are accepted:

FILES In this mode, index.html, index.xml, refman.tex, and refman.pdf are added to the result, depending on whether the corresponding format generation was requested.
DIRECTORIES In this mode, html, xml, latex, and pdf directories are added to the result (their absolute paths, to be precise).

_doxygen_list_inputs(_out_var)

Collects input file names based on the value of input parameters that control input sources: * If INPUTS is not empty, collects all files in the paths given by INPUTS. Files are added to the resulting list directly, and directories are globbed. Puts the resulting list into _out_var. * If INPUT_TARGET is not empty, takes include directories from the corresponding target. Every directory is then globbed to get the files. * If none of the above holds, an error is raised.

Parameters:

_out_var the list of files in input sources

_doxygen_output_project_file_name

_doxygen_output_project_file_name(_project_file_name _out_var)

Generates an output project file’s name, given the input name. Replaces th path to input project file _project_file_name by CMAKE_CURRENT_BINARY_DIR while leaving the file name unchanged.

_doxygen_find_directory

_doxygen_find_directory(_base_dir _names _out_var)

Searches for a directory with a name from _names, starting from _base_dir. Sets the output variable _out_var to contain absolute path of every found directory.

Setters and updaters

These functions implement property update logic:

relative directory names are converted into absolute ones;
properties derived by CMake are updated from the corresponding variables and targets.

These functions are never called directly; they are configured to participate in the property transformation process.

_doxygen_set_dia_path

_doxygen_set_dia_path(_out_var)

Sets the dot.dia-path configuration property. Puts the result into _out_var.

_doxygen_set_latex_cmd_name

_doxygen_set_latex_cmd_name(_out_var)

Sets the property output-latex.latex-cmd-name to the value of PDFLATEX_COMPILER, previously configured by find_package(LATEX). Puts the result into _out_var.

_doxygen_update_makeindex_cmd_name

_doxygen_set_makeindex_cmd_name(_out_var)

Sets output-latex.makeindex-cmd-name to the value of MAKEINDEX_COMPILER set by find_package(LATEX). Puts the result into _out_var.

_doxygen_set_input_target

_doxygen_set_input_target(_out_var)

Sets the output variable _out_var to ${PROJECT_NAME} if a target with that name exists. Clears the output variable otherwise.

_doxygen_set_warn_format

_doxygen_set_warn_format(_out_var)

Sets the value of the configuration property messages.warn-format depending on the current build tool. Puts the result into _out_var.

_doxygen_set_dot_path

_doxygen_set_dot_path(_out_var)

Sets the dot.dot-path configuration property. Uses result of the call find_package(Doxygen). Puts the result into _out_var.

_doxygen_update_input_source

_doxygen_update_input_source(<directories> <output variable>)

Walks through directory paths _paths and updates relative ones by prepending CMAKE_CURRENT_SOURCE_DIR. Does nothing to absolute directory paths. Writes updated list to _out_var.

_doxygen_update_output_dir

_doxygen_update_output_dir(_directory _out_var)

Updates a given output directory _directory:

a relative directory path is converted into an absolute one by prepending CMAKE_CURRENT_BINARY_DIR;
an absolute path stays unchanged. Puts the result into _out_var.

_doxygen_set_have_dot

_doxygen_set_have_dot(_out_var)

Sets dot.have-dot configuration flag depending on Graphviz dot presence. Uses the results of the find_package(DoxygenCMake) call. Puts the result into _out_var.

_doxygen_set_example_source

_doxygen_set_example_source(_out_var)

Setter for the property input.example-source. Searches for the sub-directories [example, examples] in the current source directory, and collects found ones. Puts the result into _out_var.

_doxygen_update_docs_target

_doxygen_update_docs_target(_out_var)

Sets the DOCS_TARGET parameter when it was not given explicitly:

if INPUT_TARGET is not empty, sets it to ${INPUT_TARGET}.doxygen;
otherwise, sets it to ${PROJECT_NAME}

Puts the result into _out_var.

_doxygen_update_generate_latex

_doxygen_update_generate_latex(_generate_latex _out_var)

If .tex generation was requested (_generate_latex is true), but no LATEX was found in the local environment, _out_var is set to false. Otherwise, it’s set to true.

Options

DOXYGEN_INSTALL_DOCS

Specifies whether the files generated by Doxygen should be installed by

make install INSTALL_COMPONENT

DOXYGEN_ADD_OPEN_TARGETS

Specifies whether open targets should be created for the files generated by Doxygen.