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.
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.
mathjax_format	Format of the MathJax output in the HTML build.
mathjax_relpath	Relative path or URL to the MathJax bundle.
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.
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_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.

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.

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.

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.

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[pathlib.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_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

A DoxygenConfiguration instance populated with configurations parsed from doxygen_conf.

Return type

doxygen_configuration

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

Text content of a doxygen configuration file.

Return type

config_content