DoxygenConfiguration

class documenteer.stackdocs.doxygen.DoxygenConfiguration(include_paths=<factory>, inputs=<factory>, image_paths=<factory>, excludes=<factory>, recursive=True, file_patterns=<factory>, exclude_patterns=<factory>, exclude_symbols=<factory>, project_name='The LSST Science Pipelines', project_brief='C++ API Reference', output_directory=<factory>, generate_html=True, generate_latex=False, tagfile=<factory>, tagfiles=<factory>, generate_xml=True, html_output=<factory>, use_mathjax=True, mathjax_format='HTML-CSS', mathjax_relpath='https://cdn.jsdelivr.net/npm/mathjax@2', xml_output=<factory>, xml_programlisting=False, create_subdirs=False, full_path_names=True, strip_from_path=<factory>, quiet=True, warnings=True, warn_if_undocumented=True, warn_if_doc_error=True, warn_no_paramdoc=False, warn_as_error=False, warn_format='$file:$line: $text', warn_logfile=None)

Bases: object

A restricted Doxygen configuration.

Rather than accomodating arbitrary Doxygen configurations, this class maintains the key configurations that are required for a Doxygen build that is intended to be incorporated into a Sphinx build. As such, this configuration file may ignore some configuration values when parsing a raw configuration file.

Notes

See http://www.doxygen.nl/manual/config.html for more details about Doxygen configurations.

Parameters:

• include_paths (List[Path], default: <factory>)

• inputs (List[Path], default: <factory>)

• image_paths (List[Path], default: <factory>)

• excludes (List[Path], default: <factory>)

• recursive (bool, default: True)

• file_patterns (List[str], default: <factory>)

• exclude_patterns (List[str], default: <factory>)

• exclude_symbols (List[str], default: <factory>)

• project_name (str, default: 'The LSST Science Pipelines')

• project_brief (str, default: 'C++ API Reference')

• output_directory (Path, default: <factory>)

• generate_html (bool, default: True)

• generate_latex (bool, default: False)

• tagfile (Path, default: <factory>)

• tagfiles (List[str], default: <factory>)

• generate_xml (bool, default: True)

• html_output (Path, default: <factory>)

• use_mathjax (bool, default: True)

• mathjax_format (str, default: 'HTML-CSS')

• mathjax_relpath (str, default: 'https://cdn.jsdelivr.net/npm/mathjax@2')

• xml_output (Path, default: <factory>)

• xml_programlisting (bool, default: False)

• create_subdirs (bool, default: False)

• full_path_names (bool, default: True)

• strip_from_path (List[Path], default: <factory>)

• quiet (bool, default: True)

• warnings (bool, default: True)

• warn_if_undocumented (bool, default: True)

• warn_if_doc_error (bool, default: True)

• warn_no_paramdoc (bool, default: False)

• warn_as_error (bool, default: False)

• warn_format (str, default: '$file:$line: $text')

• warn_logfile (Optional[Path], default: None)

Attributes Summary

create_subdirs	Whether Doxygen should create subdirectories.
exclude_patterns	Absolute file paths that match these patterns are excluded from the Doxygen build.
exclude_symbols	Symbols to exclude from the Doxygen build, such as namespace, function, or class names.
excludes	File or directory paths to be excluded from the inputs.
file_patterns	File extensions to include from the directories described by inputs.
full_path_names	Doxygen keeps the full path of each file, rather than stripping it.
generate_html	Whether or not to generate HTML output.
generate_latex	Whether or not to generate LaTeX output.
generate_xml	Whether or not ot generate XML output.
html_output	Directory where the HTML build will be put.
image_paths	Paths that contain images.
include_paths	Paths to other Doxygen configuration files.
inputs	Individual paths to be input into the doxygen build.
mathjax_format	Format of the MathJax output in the HTML build.
mathjax_relpath	Relative path or URL to the MathJax bundle.
output_directory	Directory where Doxygen output will be generated, by default.
project_brief	Brief description (subtile) of the project.
project_name	Name of the Doxygen project (used in the HTML output).
quiet	Turn off messages generated to standard output by Doxygen.
recursive	Whether or not directories listed in inputs should be searched recursively.
strip_from_path	Path prefixes to strip from path names.
tagfile	Whether or not to generate LaTeX output.
tagfiles	The TAGFILES tag can be used to specify one or more tag files.
use_mathjax	Enable MathJax to render math, rather than LaTeX.
warn_as_error	Treat warnings are errors.
warn_format	Format for warning and error messages.
warn_if_doc_error	Warn about potential errors in the documentation.
warn_if_undocumented	Warn about undocumented members.
warn_logfile	Print errors and warnings to a log file.
warn_no_paramdoc	Warn about functions that are documented but don't have documentation for their parameters or return value.
warnings	Enable warnings printed to standard error.
xml_output	Directory to output XML build products into.
xml_programlisting	Whether to include the program listing in the XML output.

Methods Summary

from_doxygen_conf(conf_text, root_dir)	Create a new DoxygenConfiguration from the the content of a doxygen.conf or doxygen.conf.in file.
render()	Render the Doxygen configuration file.

Attributes Documentation

create_subdirs: bool = False

Whether Doxygen should create subdirectories.

This should be NO for breathe/exhale to work.

exclude_patterns: List[str] = <dataclasses._MISSING_TYPE object>

Absolute file paths that match these patterns are excluded from the Doxygen build.

Pybind11 wrappers are excluded because Doxygen doesn’t handle them correctly.

exclude_symbols: List[str] = <dataclasses._MISSING_TYPE object>

Symbols to exclude from the Doxygen build, such as namespace, function, or class names.

excludes: List[Path] = <dataclasses._MISSING_TYPE object>

File or directory paths to be excluded from the inputs.

file_patterns: List[str] = <dataclasses._MISSING_TYPE object>

File extensions to include from the directories described by inputs.

full_path_names: bool = True

Doxygen keeps the full path of each file, rather than stripping it.

generate_html: bool = True

Whether or not to generate HTML output.

generate_latex: bool = False

Whether or not to generate LaTeX output.

generate_xml: bool = True

Whether or not ot generate XML output.

html_output: Path = <dataclasses._MISSING_TYPE object>

Directory where the HTML build will be put.

image_paths: List[Path] = <dataclasses._MISSING_TYPE object>

Paths that contain images.

include_paths: List[Path] = <dataclasses._MISSING_TYPE object>

Paths to other Doxygen configuration files.

This attribute is rendered as both the @INCLUDE_PATH and INCLUDE doxygen configurations.

inputs: List[Path] = <dataclasses._MISSING_TYPE object>

Individual paths to be input into the doxygen build.

mathjax_format: str = 'HTML-CSS'

Format of the MathJax output in the HTML build.

mathjax_relpath: str = 'https://cdn.jsdelivr.net/npm/mathjax@2'

Relative path or URL to the MathJax bundle.

output_directory: Path = <dataclasses._MISSING_TYPE object>

Directory where Doxygen output will be generated, by default.

project_brief: str = 'C++ API Reference'

Brief description (subtile) of the project.

project_name: str = 'The LSST Science Pipelines'

Name of the Doxygen project (used in the HTML output).

quiet: bool = True

Turn off messages generated to standard output by Doxygen.

recursive: bool = True

Whether or not directories listed in inputs should be searched recursively.

strip_from_path: List[Path] = <dataclasses._MISSING_TYPE object>

Path prefixes to strip from path names.

tagfile: Path = <dataclasses._MISSING_TYPE object>

Whether or not to generate LaTeX output.

tagfiles: List[str] = <dataclasses._MISSING_TYPE object>

The TAGFILES tag can be used to specify one or more tag files.

For each tag file the location of the external documentation should be added. The format of a tag file without this location is as follows: TAGFILES = file1 file2 … Adding location for the tag files is done as follows: TAGFILES = file1=loc1 “file2 = loc2” … where loc1 and loc2 can be relative or absolute paths or URLs. See the section “Linking to external documentation” for more information about the use of tag files. Note: Each tag file must have a unique name (where the name does NOT include the path). If a tag file is not located in the directory in which doxygen is run, you must also specify the path to the tagfile here.

use_mathjax: bool = True

Enable MathJax to render math, rather than LaTeX.

warn_as_error: bool = False

Treat warnings are errors.

warn_format: str = '$file:$line: $text'

Format for warning and error messages.

warn_if_doc_error: bool = True

Warn about potential errors in the documentation.

warn_if_undocumented: bool = True

Warn about undocumented members.

If EXTRACT_ALL is set to YES then this flag will automatically be disabled.

warn_logfile: Optional[Path] = None

Print errors and warnings to a log file.

If left blank the output is written to standard error (stderr).

warn_no_paramdoc: bool = False

Warn about functions that are documented but don’t have documentation for their parameters or return value.

If set to NO, doxygen will only warn about wrong or incomplete parameter documentation, but not about the absence of documentation.

warnings: bool = True

Enable warnings printed to standard error.

xml_output: Path = <dataclasses._MISSING_TYPE object>

Directory to output XML build products into.

xml_programlisting: bool = False

Whether to include the program listing in the XML output.

Methods Documentation

classmethod from_doxygen_conf(conf_text, root_dir)

Create a new DoxygenConfiguration from the the content of a doxygen.conf or doxygen.conf.in file.

Parameters:

• conf_text (str) – The text content of a doxygen.conf file.

• root_dir (Path) – Directory containing the doxygen.conf file. This directory path is used to resolve any relative paths within the configuration file.

Returns:

doxygen_configuration – A DoxygenConfiguration instance populated with configurations parsed from doxygen_conf.

Return type:

DoxygenConfiguration

Notes

Only select tags from the Doxygen configuration file are parsed and incorporated into the DoxygenConfiguration instance:

• INPUT

• EXCLUDE

• EXCLUDE_PATTERNS

• EXCLUDE_SYMBOLS

• IMAGE_PATH

These are the only tags that individual packages should need to configure with respect to a stack-wide Doxygen build.

render()

Render the Doxygen configuration file.

Returns:

config_content – Text content of a doxygen configuration file.

Return type:

str