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

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

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

Detailed Description

Tools related to gnerating or adding software documentation.

Copyright (c) 2011, 2012 University of Pennsylvania. All rights reserved.
See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.

Contact: SBIA Group <sbia-software at uphs.upenn.edu>

Definition in file DocTools.cmake.

Function Documentation

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.

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`.
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_DIR`, `BINARY_CODE_DIR`, `PROJECT_INCLUDE_DIR`, `BINARY_INCLUDE_DIR`.
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.
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.

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.

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`.
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_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.
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.

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

cmake __BASIS_DOCTOOLS_INCLUDED

Definition at line 16 of file DocTools.cmake.

cmake BUILDERS

Definition at line 1508 of file DocTools.cmake.

cmake HTML_INSTALLED

Definition at line 1509 of file DocTools.cmake.

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation