Doxygen

IXM provides a wrapper Doxygen package that provides a more powerful feature set for cross target and cross project Doxygen generation. Additionally, unlike CMake's Doxygen package, it relies on target properties instead of scoped variables, which allows users to use both generator expressions, as well as have per-target settings.

This find_package module wraps the CMake find_package module, so using the IXM module does not cause any issues for backwards compatibility as long as users are not relying on already documented deprecated behavior.

Usage

Use this module as you normally would. However, ensure that IXM is at the front of your CMAKE_MODULE_PATH when calling find_package(Doxygen) in a given directory.

find_package(Doxygen ...)

Use the commands and properties mentioned below to create and modify a doxygen target.

Commands

add_doxygen_target

This creates a target that can be referred to directly with set_property and set_target_properties. When building, this will read a predefined set of inputs as well as inputs provided by the user, and generate documentation via the Doxygen::doxygen target.

To add additional inputs to the target, simply use the builtin CMake target_sources command. This command can take directories as well as sources and will just work as a result.

WARNING

This command uses add_custom_target internally, which does not permit creating alias targets, nor does it permit creating "scoped" targets (e.g., ${PROJECT_NAME}::docs) as a result, all names passed to this command must be globally unique.

Required Parameters

target

name of the target you wish to create.

Keyword Parameters

ALL

Add this target to the all target dependency.

INPUT

Path to a file to use as the input template. This file is passed to file(GENERATE) from CMake with the target as the TARGET context. This file can contain generator expressions but will not be run through configure_file first at any point.

By default, this is set to a file provided by IXM.

COMMENT

Comment for the build system to display when executing Doxygen.

By default this will be "Generating documentation for target '${target}' with Doxygen ${DOXYGEN_VERSION}"

target_doxygen_tagfile

This command will add additional tag files to the provided doxygen target. Tag files are used to set links to types that Doxygen might not be able to understand (e.g., a tag file would allow documentation to link to cppreference when a type in the std:: namespace is found)

Required Parameters

target

Doxygen target you wish to add tag files to.

tagfile

Path to the tagfile

Keyword Parameters

URL

The URL the tagfile will use as its base url.

NOTE

Not all tag files will use a URL. Sometimes the paths can be relative. This is most useful when working within large interconnected projects, or projects with dependencies that might also generate Doxygen projects.

target_doxygen_extra_css

Adds additional style sheets to the given doxygen target.

Required Parameters

target

Doxygen target you wish to add style sheets to

Keyword Parameters

INTERFACE | PUBLIC | PRIVATE

These properties work like you would expect them to for any other target_<command> function found in CMake.

NOTE

There is no actual INTERFACE property equivalent at this time for the Doxygen property, and transitive linking does not work with this target type.

Properties

Only a few IXM specific properties are discussed here in detail, as IXM also takes a page from CMake's book and uses the same names for properties as would be found in a doxygen configuration file. e.g., DOXYGEN_RECURSIVE will set the RECURSIVE value inside of the generated Doxyfile. For a full list of all possible configuration names (and their default values), see Doxygen's Configuration Documentation

DOXYGEN_WORKING_DIRECTORY

The directory that Doxygen will execute from. By default, this is the SOURCE_DIR of the target

DOXYGEN_CONFIGURATION_FILE

Path to the configuration file to use. By default this is set to the file that is generated by IXM via add_doxygen_target.

DOXYGEN_TARGET_DEPENDENCIES

Additional targets that must build prior to the given doxygen target.