DependencyManagerDocs

Overview

This module simplifies building of documentation through doxygen. Each project has it’s own documentation either built locally or hosted online. Interedependencies are managed through external links using doxygen tag files.

During local build, html documentation for each project is built and tag file is generated.

If using hosted docs, tag files are downloaded and made available for use by higher level projects.

Adding Documentation for a Project

DependencyManagerDocs_Add
DependencyManagerDocs_Add(<projectName>
                [TARGETS <target1> ...]
                [FILES <extraFiles> ...]
                [DOXYFILE <doxyfile>]
                [DOC_URL <docURL>]
                [TAG_URL <tagURL>]
                [DEPENDS <dependencyName> ...])

Adds target for building documentation of project with name <projectName>.

TARGETS is followed by a list of targets whose sources and headers should be passed to Doxygen as input. If no targets are given, than target <projectName> will be used.

FILES is followed by any extra files that should be passed to Doxygen. For example, README.md from top level.

DOXYFILE is followed by name of the doxyfile configuration file as an absolut path or relative to ${CMAKE_CURRENT_SOURCE_DIR}. Defaults to Doxyfile. The configuration file should have placeholders in-between @ with cmake variable names. Some relevant CMake variables that are defined can be found below.

DOC_URL is followed by the url to external documentation. Entries in tag file must be relative to <url>. If <url> is not specified, than the documentation is always built locally.

TAG_URL is followed by the url to the tag file. If not specified, it is assumed to be <url>/DoxygenTagFiles/<projectName>.tag.

DEPENDS is followed by a list of projects whose documentation has to be build before current project. This ensures that tag files of dependencies are available.

Note

Top level project (CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR OR CMAKE_PROJECT_NAME STREQUAL <projectName>) attempts to build local documentation by default. This takes precedence over DEPENDENCYMANAGERDOCS_LOCAL but can be over-ruled by DEPENDENCYMANAGERDOCS_<projectName>_LOCAL.

Warning

To ensure tag files of children are available to parent project DependencyManagerDocs_Add() should be called as the last step.

Options

DEPENDENCYMANAGERDOCS_LOCAL

  • If ON, builds local documentation for all projects

  • Otherwise, download tag files and link to external docs.

  • Default value: OFF.

DEPENDENCYMANAGERDOCS_<projectName>_LOCAL

  • If evaluates to True, local build of documentation is forced.

  • If evaluates to False, tries to use external documentation.

  • If not set, it remains empty and not used.

  • This takes precedence over DEPENDENCYMANAGERDOCS_LOCAL and top level directory.

  • Default value: "".

DEPENDENCYMANAGERDOCS_BASE_DIR

  • Path to the base directory. Documentation for each project is built under ${DEPENDENCYMANAGERDOCS_BASE_DIR}/<projectName>/

  • Default value: ${CMAKE_BINARY_DIR}/docs.

Local Variables

Local variables that can be used in <doxyfile> configuration file:

DEPENDENCYMANAGERDOCS_PROJECT_NAME

  • name of the project, same as <projectName>

DEPENDENCYMANAGERDOCS_SOURCES

  • list of source files for the INPUT in Doxyfile

DEPENDENCYMANAGERDOCS_<name>_TAG_FILE and DEPENDENCYMANAGERDOCS_<name>_DOC_URL

  • location of tagfile and path to html (either as file path or url) for each project that has been added so far.

DEPENDENCYMANAGERDOCS_PROJECT_DOC_DIR

  • location where to put projects documentation, default ${CMAKE_BINARY_DIR}/docs/<projectName>

Example Doxyfile

Here are example lines that should be in <doxyfile>:

PROJECT_NAME = @DEPENDENCYMANAGERDOCS_PROJECT_NAME@
INPUT = @DEPENDENCYMANAGERDOCS_SOURCES@
TAGFILES = "@DEPENDENCYMANAGERDOCS_<dependencyProjectName>_TAG_FILE@=@DEPENDENCYMANAGERDOCS_<dependencyProjectName>_DOC_URL@"
GENERATE_TAGFILE = @DEPENDENCYMANAGERDOCS_PROJECT_NAME@.tag

Each dependency should contain a TAGFILES entry, use TAGFILES += on a new line to append.