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[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