0
# Breathe
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: breathe
7
- **Package Type**: Python package (Sphinx extension)
8
- **Language**: Python
9
- **Installation**: `pip install breathe`
10
- **Requirements**: Python >=3.9, Sphinx >=7.2
11

12
## Core Imports
13

14
Extension registration (in `conf.py`):
15

16
```python
17
extensions = ['breathe']
18
```
19

20
Programmatic access:
21

22
```python
23
import breathe
24
from breathe.project import ProjectInfo, ProjectInfoFactory
25
from breathe.parser import DoxygenParserFactory
26
from breathe.file_state_cache import setup as file_state_cache_setup
27
from breathe.renderer.sphinxrenderer import setup as renderer_setup
28
```
29

30
## Basic Usage
31

32
### 1. Configure in conf.py
33

34
```python
35
# Add breathe to extensions
36
extensions = ['breathe']
37

38
# Configure breathe projects
39
breathe_projects = {
40
    "myproject": "path/to/doxygen/xml/output"
41
}
42
breathe_default_project = "myproject"
43
```
44

45
### 2. Use directives in reStructuredText
46

47
```rst
48
Basic class documentation:
49

50
.. doxygenclass:: MyClass
51
   :members:
52
   :private-members:
53

54
Function documentation:
55

56
.. doxygenfunction:: myFunction
57

58
File documentation:
59

60
.. doxygenfile:: myheader.h
61
```
62

63
### 3. Command-line API generation
64

65
```bash
66
# Generate reStructuredText files from Doxygen XML
67
breathe-apidoc -o output_dir -f -m path/to/doxygen/xml
68
```
69

70
## Architecture
71

72
Breathe operates through several key components:
73

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

81
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.
82

83
## Capabilities
84

85
### Sphinx Directives
86

87
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.
88

89
```python { .api }
90
# Main entry point
91
def setup(app: Sphinx) -> dict[str, bool | str]:
92
    """
93
    Initialize Breathe extension with Sphinx.
94
    
95
    Returns:
96
        Dictionary with version and parallel processing flags:
97
        {"version": __version__, "parallel_read_safe": True, "parallel_write_safe": True}
98
    """
99
```
100

101
**Configuration options**:
102
```python { .api }
103
breathe_projects: Dict[str, str]
104
breathe_default_project: str
105
breathe_projects_source: Dict
106
breathe_build_directory: str
107
```
108

109
[Sphinx Directives](./directives.md)
110

111
### Command Line Interface
112

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

115
```python { .api }
116
def main() -> None  # Entry point for breathe-apidoc command
117
```
118

119
**Available types**: `class`, `interface`, `struct`, `union`, `file`, `namespace`, `group`
120

121
[Command Line Interface](./cli.md)
122

123
### Project Management
124

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

127
```python { .api }
128
class ProjectInfo:
129
    def __init__(app: Sphinx, name: str, path: str, source_path: str, reference: str)
130
    def name() -> str
131
    def project_path() -> str
132
    def relative_path_to_xml_file(file_: str) -> str
133

134
class ProjectInfoFactory:
135
    def __init__(app: Sphinx)
136
    def create_project_info(options: dict) -> ProjectInfo
137
```
138

139
[Project Management](./project-management.md)
140

141
### Parser System
142

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

145
```python { .api }
146
class DoxygenParserFactory:
147
    def __init__(app: Sphinx)
148
    def create_index_parser() -> DoxygenIndexParser
149
    def create_compound_parser(project_info: ProjectInfo) -> DoxygenCompoundParser
150
    
151
class DoxygenIndexParser:
152
    def parse(project_info: ProjectInfo)
153

154
class DoxygenCompoundParser:  
155
    def parse(refid: str)
156
```
157

158
[Parser System](./parsers.md)
159

160
## Configuration Options
161

162
Breathe provides extensive configuration through Sphinx's config system:
163

164
### Project Configuration
165
- `breathe_projects` - Map project names to XML directories
166
- `breathe_default_project` - Default project when none specified
167
- `breathe_projects_source` - Source paths for auto-generation
168
- `breathe_build_directory` - Build directory for auto-generation
169

170
### Display Options  
171
- `breathe_default_members` - Default member inclusion settings
172
- `breathe_show_define_initializer` - Show preprocessor define values
173
- `breathe_show_enumvalue_initializer` - Show enum value initializers
174
- `breathe_show_include` - Show include statements in file docs
175
- `breathe_separate_member_pages` - Create separate pages for members
176

177
### Advanced Options
178
- `breathe_domain_by_extension` - File extension to Sphinx domain mapping (default: {"py": "py", "cs": "cs"})
179
- `breathe_domain_by_file_pattern` - File pattern to domain mapping  
180
- `breathe_use_project_refids` - Use project-specific reference IDs
181
- `breathe_order_parameters_first` - Order parameters before descriptions
182
- `breathe_implementation_filename_extensions` - File extensions for implementation files (default: [".c", ".cc", ".cpp"])
183
- `breathe_separate_member_pages` - Create separate pages for members (default: False)
184
- `breathe_doxygen_config_options` - Doxygen configuration overrides
185
- `breathe_doxygen_aliases` - Doxygen command aliases
186

187
## Exception Classes
188

189
```python { .api }
190
class BreatheError(Exception): ...
191
    
192
class ProjectError(BreatheError): ...
193

194
class NoDefaultProjectError(ProjectError): ...
195

196
# Parser exceptions
197
class ParserError(Exception):
198
    def __init__(self, error: Exception, filename: Path): ...
199
    @property
200
    def error(self) -> Exception: ...
201
    @property  
202
    def filename(self) -> Path: ...
203

204
class FileIOError(Exception):
205
    def __init__(self, error: Exception, filename: Path): ...
206
    @property
207
    def error(self) -> Exception: ...
208
    @property
209
    def filename(self) -> Path: ...
210

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

214
class UnrecognisedKindError(Exception): ...
215

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

219
class _UnableToResolveFunctionError(BreatheError): ...
220
```