Breathe Documentation

Breathe acts as a bridge between Doxygen XML output and Sphinx, converting Doxygen XML nodes into docutils reStructuredText (rst) nodes. The architecture is divided into several functional areas:

• Directives: The entry point for Sphinx users. It contains the rst directive definitions used in documentation files. The directives submodule handles the registration with Sphinx and wires together the necessary factories.
• Finder: Responsible for locating specific nodes within the XML files generated by Doxygen. Finders are typically used by directives to locate the relevant XML node before passing it to a renderer.
• Renderer: Converts Doxygen XML nodes into docutils rst nodes. Breathe focuses on producing rst nodes rather than specific output formats like HTML or LaTeX, leaving the final rendering to Sphinx.
• Parser: Parses Doxygen XML into a tree of Python objects. Much of this logic is contained in the automatically generated _parser module.
• Project: Represents a Project, which is the Breathe abstraction for a directory containing Doxygen XML files.
• Process: Manages the execution of the doxygen process, specifically when using autodoxygen directives.
• Exception: Provides a base class for all custom Breathe exceptions.

Breathe relies on Doxygen's XML output, which consists of multiple files. The central entry point is always index.xml.

• index.xml: Contains a list of all generated files and a summary of their contents (e.g., which classes or files are present).
• Compound Files: For any item in index.xml, the refid attribute points to a specific XML file containing detailed information. You can locate the detailed file by appending .xml to the refid value (e.g., refid="class_test" $\rightarrow$ class_test.xml).

These compound files contain the specific documentation and markup extracted from your source code.

<!-- Example index.xml snippet -->
<doxygenindex ...>
  <compound refid="class_test" kind="class">
    <name>Test</name>
    <member refid="class_test_1a45b6a232a4499f8ce37062eab5451570" kind="function">
      <name>member</name>
    </member>
  </compound>
  <compound refid="func_8h" kind="file">
    <name>func.h</name>
  </compound>
</doxygenindex>

Breathe operates through three main functional stages to transform Doxygen XML into Sphinx documentation:

1. Parser (breathe.parser): Reads the Doxygen XML output and creates a hierarchy of Python objects representing the data.
2. Finders (breathe.finder): Searches the object hierarchy created by the parser to locate specific reference objects (e.g., a specific class or function requested by a directive).
3. Renderers (breathe.renderer): Takes the objects found by the finders and produces reStructuredText (RST) nodes. Renderers typically traverse object hierarchies to render objects and their descendants.

The data flow is: Code $\rightarrow$ Doxygen $\rightarrow$ XML $\rightarrow$ Breathe Parser $\rightarrow$ Breathe Filter $\rightarrow$ Breathe Finder $\rightarrow$ Breathe Renderer $\rightarrow$ RST Nodes $\rightarrow$ Sphinx $\rightarrow$ HTML/LaTeX.

Finders are responsible for navigating the Python object hierarchy produced by the parser to find a single target node for the renderers.

Key Mechanics:

• Entry Points: Finders use the parser's entry points (found in breathe.parser.doxygen.compound and breathe.parser.doxygen.index) to parse the XML and build the hierarchy.
• Filtering: Finders use Filter objects to determine if a node matches the search criteria. Filters can represent logical conditions like and or or and can match at different levels of the XML hierarchy.
• Recursive Search Pattern: The search often follows a hierarchical pattern. For example, a DoxygenTypeSubItemFinder might look at the root, find a match for a compound node, and then create a CompoundTypeSubItemFinder to look at members. If a member matches, it might create a MemberTypeSubItemFinder and then parse the corresponding detailed XML file (using the refid + .xml logic) to continue the search deeper.