0
# Project Management
1
2
Breathe's project management system handles multiple Doxygen projects, XML paths, source paths, and automatic XML generation. It provides a clean abstraction for working with Doxygen output while supporting both manual and automatic workflows.
3
4
## Capabilities
5
6
### ProjectInfo Class
7
8
Represents a configured Doxygen project with XML output location and metadata.
9
10
```python { .api }
11
class ProjectInfo:
12
def __init__(self, app: Sphinx, name: str, path: str, source_path: str, reference: str):
13
"""
14
Initialize project information.
15
16
Args:
17
app: Sphinx application instance
18
name: Project name identifier
19
path: Path to Doxygen XML output directory
20
source_path: Path to source files for auto-generation
21
reference: Reference identifier for the project
22
"""
23
24
def name(self) -> str:
25
"""Get the project name identifier."""
26
27
def project_path(self) -> str:
28
"""Get the path to Doxygen XML output directory."""
29
30
def source_path(self) -> str:
31
"""Get the path to source files."""
32
33
def relative_path_to_xml_file(self, file_: str) -> str:
34
"""
35
Get relative path from Sphinx source directory to XML file.
36
37
Args:
38
file_: XML filename relative to project XML directory
39
40
Returns:
41
Relative path from Sphinx srcdir to the specified XML file
42
"""
43
44
def sphinx_abs_path_to_file(self, file_: str) -> str:
45
"""
46
Get Sphinx absolute path to XML file.
47
48
Prepends os.path.sep to create Sphinx's concept of absolute path
49
which starts from the top-level source directory.
50
51
Args:
52
file_: XML filename relative to project XML directory
53
54
Returns:
55
Sphinx absolute path starting with os.path.sep
56
"""
57
58
def reference(self) -> str:
59
"""Get the project reference identifier."""
60
61
def source_path(self) -> str:
62
"""Get the path to source files."""
63
64
def domain_for_file(self, file_: str) -> str:
65
"""
66
Determine Sphinx domain for a given file.
67
68
Uses breathe_domain_by_extension and breathe_domain_by_file_pattern
69
configuration to map files to appropriate Sphinx domains.
70
71
Args:
72
file_: Filename to check
73
74
Returns:
75
Domain name (e.g., 'py', 'cs') or empty string if no match
76
"""
77
```
78
79
### AutoProjectInfo Class
80
81
Handles projects with automatic Doxygen XML generation from source files.
82
83
```python { .api }
84
class AutoProjectInfo:
85
def __init__(self, app: Sphinx, name: str, source_path: str, build_dir: str, reference: str):
86
"""
87
Initialize auto-generation project information.
88
89
Args:
90
app: Sphinx application instance
91
name: Project name identifier
92
source_path: Path to source files for XML generation
93
build_dir: Directory for generated XML output
94
reference: Reference identifier for the project
95
"""
96
97
def name(self) -> str:
98
"""Get the project name identifier."""
99
100
def build_dir(self) -> str:
101
"""Get the build directory for XML generation."""
102
103
def abs_path_to_source_file(self, file_: str) -> str:
104
"""
105
Get absolute path to source file.
106
107
Returns full path assuming the provided path is relative to the
108
project's source directory as specified in breathe_projects_source.
109
110
Args:
111
file_: Filename relative to project source directory
112
113
Returns:
114
Absolute path to the source file
115
"""
116
117
def create_project_info(self, project_path: str) -> ProjectInfo:
118
"""
119
Create a standard ProjectInfo from this AutoProjectInfo.
120
121
Args:
122
project_path: Path where XML was generated
123
124
Returns:
125
ProjectInfo instance for the generated XML
126
"""
127
```
128
129
### ProjectInfoFactory Class
130
131
Factory for creating and managing ProjectInfo instances with caching and configuration resolution.
132
133
```python { .api }
134
class ProjectInfoFactory:
135
def __init__(self, app: Sphinx):
136
"""
137
Initialize the factory with Sphinx application.
138
139
Args:
140
app: Sphinx application instance
141
"""
142
143
@property
144
def build_dir(self) -> str:
145
"""
146
Get build directory for auto-generation.
147
148
Uses breathe_build_directory config if set, otherwise uses
149
parent directory of Sphinx doctreedir.
150
"""
151
152
def default_path(self) -> str:
153
"""
154
Get default XML path from configuration.
155
156
Returns:
157
Path from breathe_projects[breathe_default_project]
158
159
Raises:
160
NoDefaultProjectError: If no default project configured
161
ProjectError: If default project not found in breathe_projects
162
"""
163
164
def create_project_info(self, options: dict) -> ProjectInfo:
165
"""
166
Create ProjectInfo from directive options.
167
168
Resolves project from options['project'], options['path'], or default.
169
Caches created instances for reuse.
170
171
Args:
172
options: Directive options dictionary
173
174
Returns:
175
ProjectInfo instance
176
177
Raises:
178
ProjectError: If specified project not found in configuration
179
"""
180
181
def store_project_info_for_auto(self, name: str, project_info: AutoProjectInfo) -> None:
182
"""
183
Store AutoProjectInfo for auto-generation directives.
184
185
Args:
186
name: Project name for storage key
187
project_info: AutoProjectInfo instance to store
188
"""
189
190
def retrieve_project_info_for_auto(self, options: dict) -> AutoProjectInfo:
191
"""
192
Retrieve stored AutoProjectInfo for auto-generation.
193
194
Args:
195
options: Directive options dictionary
196
197
Returns:
198
AutoProjectInfo instance
199
200
Raises:
201
NoDefaultProjectError: If no project specified and no default
202
"""
203
204
def create_auto_project_info(self, name: str, source_path: str) -> AutoProjectInfo:
205
"""
206
Create AutoProjectInfo for auto-generation.
207
208
Caches created instances for reuse.
209
210
Args:
211
name: Project name identifier
212
source_path: Path to source files
213
214
Returns:
215
AutoProjectInfo instance
216
"""
217
```
218
219
## Configuration Integration
220
221
The project management system integrates with several Sphinx configuration values:
222
223
### Required Configuration
224
225
```python { .api }
226
# Project mapping - required for basic functionality
227
breathe_projects = {
228
"project1": "/path/to/project1/xml",
229
"project2": "/path/to/project2/xml"
230
}
231
232
# Default project when none specified in directives
233
breathe_default_project = "project1"
234
```
235
236
### Auto-generation Configuration
237
238
```python { .api }
239
# Source paths for automatic XML generation
240
breathe_projects_source = {
241
"project1": "/path/to/project1/source",
242
"project2": "/path/to/project2/source"
243
}
244
245
# Build directory for generated XML (optional)
246
breathe_build_directory = "/custom/build/path"
247
```
248
249
### Domain Configuration
250
251
```python { .api }
252
# Map file extensions to Sphinx domains
253
breathe_domain_by_extension = {
254
"py": "py",
255
"cs": "cs",
256
"java": "java"
257
}
258
259
# Map file patterns to Sphinx domains
260
breathe_domain_by_file_pattern = {
261
"*/python/*": "py",
262
"*/csharp/*": "cs"
263
}
264
```
265
266
## Usage Examples
267
268
### Basic Project Setup
269
270
```python
271
# In conf.py
272
breathe_projects = {
273
"mylib": "doxygen/xml"
274
}
275
breathe_default_project = "mylib"
276
277
# In directive
278
.. doxygenclass:: MyClass
279
:project: mylib
280
```
281
282
### Multiple Projects
283
284
```python
285
# In conf.py
286
breathe_projects = {
287
"core": "build/core/xml",
288
"plugins": "build/plugins/xml",
289
"examples": "build/examples/xml"
290
}
291
breathe_default_project = "core"
292
293
# In directives
294
.. doxygenclass:: CoreClass
295
:project: core
296
297
.. doxygenclass:: PluginClass
298
:project: plugins
299
```
300
301
### Auto-generation Setup
302
303
```python
304
# In conf.py
305
breathe_projects_source = {
306
"mylib": "src/"
307
}
308
breathe_doxygen_config_options = {
309
"EXTRACT_ALL": "YES",
310
"EXTRACT_PRIVATE": "YES"
311
}
312
313
# Auto directives generate XML automatically
314
.. autodoxygenfile:: myheader.h
315
:project: mylib
316
```
317
318
### Custom Build Directory
319
320
```python
321
# In conf.py
322
breathe_build_directory = "/tmp/breathe_build"
323
breathe_projects_source = {
324
"mylib": "src/"
325
}
326
327
# XML will be generated in /tmp/breathe_build/mylib/
328
```
329
330
### Domain-specific Configuration
331
332
```python
333
# In conf.py
334
breathe_domain_by_extension = {
335
"py": "py",
336
"cs": "cs"
337
}
338
breathe_domain_by_file_pattern = {
339
"*/bindings/*.py": "py",
340
"*/managed/*.cs": "cs"
341
}
342
343
# Files will be processed with appropriate domain settings
344
```
345
346
### Programmatic Access
347
348
```python
349
from breathe.project import ProjectInfoFactory
350
351
# In Sphinx extension
352
def setup(app):
353
factory = ProjectInfoFactory(app)
354
355
# Create project info from options
356
options = {"project": "mylib"}
357
project_info = factory.create_project_info(options)
358
359
# Use project info
360
xml_path = project_info.project_path()
361
domain = project_info.domain_for_file("example.py")
362
```
363
364
## Exception Classes
365
366
```python { .api }
367
class ProjectError(BreatheError):
368
"""Raised when project configuration or resolution fails."""
369
370
class NoDefaultProjectError(ProjectError):
371
"""Raised when no default project is configured but required."""
372
```
373
374
Common scenarios:
375
- **ProjectError**: Invalid project name in directive options
376
- **NoDefaultProjectError**: No `:project:` option and no `breathe_default_project` set
377
- **ProjectError**: Default project name not found in `breathe_projects` dictionary