DocTools.cmake File Reference

Tools related to gnerating or adding software documentation. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
function	basis_add_changelog ()
	Add target for generation of ChangeLog file. More...
function	basis_add_doc (in TARGET_NAME, in ARGN)
	Add documentation target. More...
function	basis_add_doxygen_doc (in TARGET_NAME, in ARGN)
	Add documentation to be generated by Doxygen. More...
function	basis_add_sphinx_doc (in TARGET_NAME, in ARGN)
	Add documentation target to be generated by Sphinx (sphinx-build). More...
function	basis_install_doc (in SOURCE, in ARGN)
	Install documentation file(s). More...

Variables
cmake	__BASIS_DOCTOOLS_INCLUDED
cmake	BUILDERS
cmake	HTML_INSTALLED

Detailed Description

Tools related to gnerating or adding software documentation.

Definition in file DocTools.cmake.

Function Documentation

basis_add_changelog()

function basis_add_changelog

(

)

Add target for generation of ChangeLog file.

The ChangeLog is either generated from the Subversion or Git log depending on which revision control system is used by the project. Moreover, the project's source directory must be either a Subversion working copy or the root of a Git repository, respectively. In case of Subversion, if the command-line tool svn2cl(.sh) is installed, it is used to output a nicer formatted change log.

Returns

Nothing.

basis_add_doxygen_doc()

function basis_add_doxygen_doc	(	in	TARGET_NAME,
		in	ARGN
	)

Add documentation to be generated by Doxygen.

This function adds a build target to generate documentation from in-source code comments and other related project pages using Doxygen.

Parameters

[in]	TARGET_NAME	Name of the documentation target.
[in]	ARGN	List of arguments. The valid arguments are:

EXCLUDE_FROM_DOC	By default, the specified target is build as part of the global doc target. If this option is given, however, the added documentation will not be build as part of this target.
COMPONENT component	Name of the component this documentation belongs to. Defaults to BASIS_LIBRARY_COMPONENT.
DESTINATION dir	Installation directory prefix. Defaults to BASIS_INSTALL_&ltTARGET>_DIR in case of HTML output if set. Otherwise, the generated HTML files are not installed.
DOXYFILE file	Name of the template Doxyfile.
PROJECT_NAME name	Value for Doxygen's PROJECT_NAME tag which is used to specify the project name. Default: PROJECT_NAME.
PROJECT_NUMBER version	Value for Doxygen's PROJECT_NUMBER tag which is used to specify the project version number. Default: PROJECT_RELEASE.
PROJECT_WEBSITE url	Used for links to project website. Default: PROJECT_PACKAGE_WEBSITE
INPUT path1 [path2 ...]	Value for Doxygen's INPUT tag which is used to specify input directories/files. Any given input path is added to the default input paths. Default: PROJECT_CODE_DIRS, BINARY_CODE_DIR, PROJECT_INCLUDE_DIRS, BINARY_INCLUDE_DIR.
EXCLUDE_BASIS_MODULES	Do not add project CMake files used and generated by BASIS to INPUT.
EXCLUDE_BASIS_UTILITIES	Do not add documentation (.dox) files for used CMake BASIS Utilities to INPUT.
INPUT_FILTER filter	Value for Doxygen's INPUT_FILTER tag which can be used to specify a default filter for all input files. Default: doxyfilter of BASIS.
FILTER_PATTERNS pattern1 [pattern2...]	Value for Doxygen's FILTER_PATTERNS tag which can be used to specify filters on a per file pattern basis. Default: None.
INCLUDE_PATH path1 [path2...]	Doxygen's INCLUDE_PATH tag can be used to specify one or more directories that contain include files that are not input files but should be processed by the preprocessor. Any given directories are appended to the default include path considered. Default: Directories added by basis_include_directories().
EXCLUDE_PATTERNS pattern1 [pattern2 ...]	Additional patterns used for Doxygen's EXCLUDE_PATTERNS tag which can be used to specify files and/or directories that should be excluded from the INPUT source files. Default: No exclude patterns.
PREDEFINED name1|name1=value1 [name2|name2=value2...]	Add preprocessor definitions to be expanded by Doxygen.
OUTPUT fmt	Specify output formats in which to generate the documentation. Currently, only html and xml are supported.
OUTPUT_DIRECTORY dir	Value for Doxygen's OUTPUT_DIRECTORY tag which can be used to specify the output directory. The output files are written to subdirectories named "html", "latex", "rtf", and "man". Default: CMAKE_CURRENT_BINARY_DIR/TARGET_NAME.
COLS_IN_ALPHA_INDEX n	Number of columns in alphabetical index. Default: 3.
IGNORE_PREFIX prefix1 [prefix2...]	In case all classes in a project start with a common prefix, all classes will be put under the same header in the alphabetical index. The IGNORE_PREFIX tag can be used to specify one or more prefixes that should be ignored while generating the index headers.
PROVIDER_NAME name	Value for provider name, such as a company name, that will be used for pages in the doxygen output. Default: PROJECT_PROVIDER_NAME.
PROVIDER_WEBSITE url	Value for provider website, such as a company website, that will be used for pages in the doxygen output. Default: PROJECT_PROVIDER_WEBSITE.
PROVIDER_LOGO image_file	Value for provider logo file, such as a company logo, that will be used for pages in the doxygen output. Default: PROJECT_PROVIDER_LOGO.
DIVISION_NAME name	Value for division name, such as a company division name, that will be used for pages in the doxygen output. Default: PROJECT_DIVISION_NAME.
DIVISION_WEBSITE url	Value for division website, such as a company division website, that will be used for pages in the doxygen output. Default: PROJECT_DIVISION_WEBSITE.
DIVISION_LOGO image_file	Value for division logo file, such as a company division logo, that will be used for pages in the doxygen output. Default: PROJECT_DIVISION_LOGO.
ENABLED_SECTIONS section1 [section2 ...]	The ENABLED_SECTIONS tag can be used to enable conditional documentation sections, marked by "\if sectionname ... \endif".
HTML_HEADER html_file	The HTML_HEADER tag can be used to specify a personal HTML header for each generated HTML page. If none specified, the "PROJECT_SOURCE_DIR/doc/doxygen_header.html(.in)?" file is used if present. Otherwise, a default header is used. Specify the value Doxygen to use the standard header generated by Doxygen instead.
HTML_FOOTER html_file	The HTML_FOOTER tag can be used to specify a personal HTML footer for each generated HTML page. If none specified, the "PROJECT_SOURCE_DIR/doc/doxygen_footer.html(.in)?" file is used if present. Otherwise, a default footer is used. Specify the value Doxygen to use the standard footer generated by Doxygen instead.
HTML_EXTRA_STYLESHEET css_file	The HTML_EXTRA_STYLESHEET tag can be used to specify a user-defined cascading style sheet that is used by each HTML page. It can be used to fine-tune the look of the HTML output. If none specified, the "PROJECT_SOURCE_DIR/doc/doxygen_extra.css(.in)?" file is used if present.
HTML_EXTRA_FILES file1 [file2...]	The HTML_EXTRA_FILES tag can be used to specify additional files needed for the HTML output of the API documentation.
DISABLE_PROJECT_NAME_DISPLAY	The DISABLE_PROJECT_NAME_DISPLAY option causes Doxygen's PROJECT_NAME text not to be displayed in the header. Use this if the project name is already part of the logo so it won't be there twice in the logo image and title text.

See here for a documentation of the Doxygen tags.

Example:

basis_add_doxygen_doc (
  apidoc
  DOXYFILE        "Doxyfile.in"
  PROJECT_NAME    "${PROJECT_NAME}"
  PROJECT_VERSION "${PROJECT_VERSION}"
  COMPONENT       dev
)

See also

basis_add_doc()

Returns

Nothing.

basis_add_sphinx_doc()

function basis_add_sphinx_doc	(	in	TARGET_NAME,
		in	ARGN
	)

Add documentation target to be generated by Sphinx (sphinx-build).

This function adds a build target to generate documentation from reStructuredText (.rst files) using Sphinx.

Parameters

[in]	TARGET_NAME	Name of the documentation target.
[in]	ARGN	List of arguments. The valid arguments are:

EXCLUDE_FROM_DOC	By default, the specified target is build as part of the global doc target. If this option is given, however, the added documentation will not be build as part of this target.
BUILDER(S) builder...	Sphinx builders to use. For each named builder, a build target named <TARGET_NAME>_<builder> is added.
DEFAULT_BUILDER builder	Default Sphinx builder to associated with the TARGET_NAME build target. Defaults to the first builder named by BUILDERS.
AUTHOR(S) name	Names of authors who wrote this documentation. (default: PROJECT_AUTHORS)
COPYRIGHT text	Copyright statement for generated files. (default: PROJECT_COPYRIGHT)
COMPONENT component	Name of the component this documentation belongs to. Defaults to BASIS_RUNTIME_COMPONENT.
DESTINATION dir	Installation directory prefix. Used whenever there is no specific destination specified for a particular Sphinx builder. Defaults to BASIS_INSTALL_&ltTARGET>_DIR in case of HTML output if set. Otherwise, the generated HTML files are not installed.
<BUILDER>_DESTINATION dir	Installation directory for files generated by the specific builder.
EXTENSIONS ext...	Names of Sphinx extensions to enable.
BREATHE target...	Adds a project for the breathe extension which allows the inclusion of in-source code documentation extracted by Doxygen. For this to work, the specified Doxygen target has to be configured with the XML output enabled.
DOXYLINK target...	Adds a role for the doxylink Sphinx extension which allows to cross-reference generated HTML API documentation generated by Doxygen.
DOXYLINK_URL url	URL to Doxygen documentation. Use DOXYLINK_PREFIX and/or DOXYLINK_SUFFIX instead if you use multiple Doxygen targets, where the target name is part of the URL.
DOXYLINK_PREFIX url	Prefix to use for links to Doxygen generated documentation pages as generated by the doxylink Sphinx extension. If this prefix does not start with a protocol such as http:// or https://, it is prefixed to the default path determined by this function relative to the build or installed Doxygen documentation.
DOXYLINK_SUFFIX suffix	Suffix for links to Doxygen generated documentation pages as generated by the doxylink Sphinx extension.
DOXYDOC target...	Alias for both BREATHE and DOXYLINK options.
CONFIG_FILE file	Sphinx configuration file. Defaults to BASIS_SPHINX_CONFIG.
SOURCE_DIRECTORY	Root directory of Sphinx source files. Defaults to the current source directory or, if a subdirectory named TARGET_NAME in lowercase only exists, to this subdirectory.
OUTPUT_NAME	Output name for generated documentation such as PDF document or MAN page. Defaults to PROJECT_NAME.
OUTPUT_DIRECTORY	Root output directory for generated files. Defaults to the binary directory corresponding to the set SOURCE_DIRECTORY.
TAG tag	Tag argument of sphinx-build.
TEMPLATES_PATH	Path to template files. Defaults to SOURCE_DIRECTORY/templates/.
MASTER_DOC name	Name of master document. Defaults to index.
EXCLUDE_PATTERN pattern	A glob-style pattern that should be excluded when looking for source files. Specify this option more than once to specify multiple exclude patterns. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.
HTML_TITLE title	Title of HTML web site.
HTML_THEME theme	Name of HTML theme. Defaults to the sbia theme included with BASIS.
HTML_THEME_PATH dir	Directory of HTML theme. Defaults to BASIS_SPHINX_HTML_THEME_PATH.
HTML_LOGO file	Logo to display in sidebar of HTML pages.
HTML_FAVICON file	Favorite square icon often displayed by browsers in the tab bar. Should be a .ico file.
HTML_STATIC_PATH dir	Directory for static files of HTML pages. Defaults to SOURCE_DIRECTORY/static/.
HTML_STYLE css	The style sheet to use for HTML pages. A file of that name must exist either in Sphinx' default static/ path or the specified HTML_STATIC_PATH. Default is the stylesheet given by the selected theme. If you only want to add or override a few things compared to the theme’s stylesheet, use CSS @import to import the theme’s stylesheet.
HTML_SIDEBARS name...	Names of HTML template files for sidebar(s). Defaults to none if not specified. Valid default templates are localtoc, globaltoc, searchbox, relations, sourcelink. See Shinx documentation of html_sidebars option. Custom templates can be used as well by copying the template .html file to the TEMPLATES_PATH directory.
NO_HTML_DOMAIN_INDICES	Set Sphinx configuration option html_domain_indices to False. (Default: True)
NO_HTML_MODINDEX	Set Sphinx configuration option html_use_modindex to False. (Default: True)
NO_HTML_INDEX	Set Sphinx configuration option html_use_index to False. (Default: True)
LATEX_MASTER_DOC name	Name of master document for LaTeX builder. Defaults to MASTER_DOC.
LATEX_TITLE title	Title for LaTeX/PDF output. Defaults to title of index.rst.
LATEX_LOGO file	Logo to display above title in generated LaTeX/PDF output.
LATEX_DOCUMENT_CLASS howto|manual	Document class to use by latex builder.
LATEX_SHOW_URLS	See Sphinx documentation of the latex_show_urls option.
LATEX_SHOW_PAGEREFS	See Sphinx documentation of the latex_show_pagerefs option.
MAN_SECTION num	Section number for manual pages generated by man builder.

See also

basis_add_doc()

Returns

Nothing.

basis_install_doc()

function basis_install_doc	(	in	SOURCE,
		in	ARGN
	)

Install documentation file(s).

This function either adds an installation rule for a single documentation file or a directory containing multiple documentation files.

Example:

basis_install_doc ("User Manual.pdf" OUTPUT_NAME "BASIS User Manual.pdf")
basis_install_doc (DeveloperManual.docx COMPONENT dev)
basis_install_doc (SourceManual.html    COMPONENT src)

Parameters

[in]	SOURCE	Documentation file or directory to install.
[in]	ARGN	List of optional arguments. Valid arguments are:

COMPONENT component	Name of the component this documentation belongs to. Defaults to BASIS_RUNTIME_COMPONENT.
DESTINATION dir	Installation directory prefix. Defaults to INSTALL_DOC_DIR.
OUTPUT_NAME name	Name of file or directory after installation.

See also

basis_add_doc()

Returns

Nothing.

Variable Documentation

__BASIS_DOCTOOLS_INCLUDED

cmake __BASIS_DOCTOOLS_INCLUDED

Definition at line 21 of file DocTools.cmake.

BUILDERS

cmake BUILDERS

Definition at line 1866 of file DocTools.cmake.

HTML_INSTALLED

cmake HTML_INSTALLED

Definition at line 1867 of file DocTools.cmake.