Breathe

A Sphinx extension that beautifully integrates Doxygen-generated documentation into Sphinx-based documentation systems. Breathe serves as a bridge between Doxygen's excellent technical understanding of code bases (particularly C/C++ code) and Sphinx's superior long-form documentation capabilities.

Package Information

• Package Name: breathe
• Package Type: Python package (Sphinx extension)
• Language: Python
• Installation: pip install breathe
• Requirements: Python >=3.9, Sphinx >=7.2

Core Imports

Extension registration (in conf.py):

extensions = ['breathe']

Programmatic access:

import breathe
from breathe.project import ProjectInfo, ProjectInfoFactory
from breathe.parser import DoxygenParserFactory
from breathe.file_state_cache import setup as file_state_cache_setup
from breathe.renderer.sphinxrenderer import setup as renderer_setup

Basic Usage

1. Configure in conf.py

# Add breathe to extensions
extensions = ['breathe']

# Configure breathe projects
breathe_projects = {
    "myproject": "path/to/doxygen/xml/output"
}
breathe_default_project = "myproject"

2. Use directives in reStructuredText

Basic class documentation:

.. doxygenclass:: MyClass
   :members:
   :private-members:

Function documentation:

.. doxygenfunction:: myFunction

File documentation:

.. doxygenfile:: myheader.h

3. Command-line API generation

# Generate reStructuredText files from Doxygen XML
breathe-apidoc -o output_dir -f -m path/to/doxygen/xml

Architecture

Breathe operates through several key components:

• Directives: Sphinx directives that parse directive arguments and render documentation
• Parsers: XML parsers that process Doxygen's XML output format
• Finders: Classes that locate specific elements within parsed XML trees
• Renderers: Components that convert parsed XML into Sphinx/docutils nodes
• Filters: Systems for selecting and customizing which elements to document
• Project Management: Classes for handling multiple Doxygen projects and their configurations

The extension integrates deeply with Sphinx's configuration system, directive framework, and build process to provide seamless documentation generation while maintaining full control over output formatting and organization.

Capabilities

Sphinx Directives

Core functionality accessed through reStructuredText directives for documenting C/C++ code elements. Includes directives for classes, functions, files, namespaces, and more with extensive customization options.

# Main entry point
def setup(app: Sphinx) -> dict[str, bool | str]:
    """
    Initialize Breathe extension with Sphinx.
    
    Returns:
        Dictionary with version and parallel processing flags:
        {"version": __version__, "parallel_read_safe": True, "parallel_write_safe": True}
    """

Configuration options:

breathe_projects: Dict[str, str]
breathe_default_project: str
breathe_projects_source: Dict
breathe_build_directory: str

Sphinx Directives

Command Line Interface

Command-line tool for batch generation of reStructuredText files from Doxygen XML output, supporting various output types and customization options.

def main() -> None  # Entry point for breathe-apidoc command

Available types: class, interface, struct, union, file, namespace, group

Command Line Interface

Project Management

Classes for managing Doxygen projects, handling XML paths, source paths, and project-specific configuration. Supports both manual project setup and automatic XML generation.

class ProjectInfo:
    def __init__(app: Sphinx, name: str, path: str, source_path: str, reference: str)
    def name() -> str
    def project_path() -> str
    def relative_path_to_xml_file(file_: str) -> str

class ProjectInfoFactory:
    def __init__(app: Sphinx)
    def create_project_info(options: dict) -> ProjectInfo

Project Management

Parser System

XML parsing system for processing Doxygen's XML output, with caching support and comprehensive error handling for index files and compound definitions.

class DoxygenParserFactory:
    def __init__(app: Sphinx)
    def create_index_parser() -> DoxygenIndexParser
    def create_compound_parser(project_info: ProjectInfo) -> DoxygenCompoundParser
    
class DoxygenIndexParser:
    def parse(project_info: ProjectInfo)

class DoxygenCompoundParser:  
    def parse(refid: str)

Parser System

Configuration Options

Breathe provides extensive configuration through Sphinx's config system:

Project Configuration

• breathe_projects - Map project names to XML directories
• breathe_default_project - Default project when none specified
• breathe_projects_source - Source paths for auto-generation
• breathe_build_directory - Build directory for auto-generation

Display Options

• breathe_default_members - Default member inclusion settings
• breathe_show_define_initializer - Show preprocessor define values
• breathe_show_enumvalue_initializer - Show enum value initializers
• breathe_show_include - Show include statements in file docs
• breathe_separate_member_pages - Create separate pages for members

Advanced Options

• breathe_domain_by_extension - File extension to Sphinx domain mapping (default: {"py": "py", "cs": "cs"})
• breathe_domain_by_file_pattern - File pattern to domain mapping
• breathe_use_project_refids - Use project-specific reference IDs
• breathe_order_parameters_first - Order parameters before descriptions
• breathe_implementation_filename_extensions - File extensions for implementation files (default: [".c", ".cc", ".cpp"])
• breathe_separate_member_pages - Create separate pages for members (default: False)
• breathe_doxygen_config_options - Doxygen configuration overrides
• breathe_doxygen_aliases - Doxygen command aliases

Exception Classes

class BreatheError(Exception): ...
    
class ProjectError(BreatheError): ...

class NoDefaultProjectError(ProjectError): ...

# Parser exceptions
class ParserError(Exception):
    def __init__(self, error: Exception, filename: Path): ...
    @property
    def error(self) -> Exception: ...
    @property  
    def filename(self) -> Path: ...

class FileIOError(Exception):
    def __init__(self, error: Exception, filename: Path): ...
    @property
    def error(self) -> Exception: ...
    @property
    def filename(self) -> Path: ...

# Cache and processing exceptions  
class MTimeError(Exception): ...

class UnrecognisedKindError(Exception): ...

# Function-specific exceptions
class _NoMatchingFunctionError(BreatheError): ...

class _UnableToResolveFunctionError(BreatheError): ...