0
# Sphinx Directives
1

2
Breathe provides 17 Sphinx directives for documenting C/C++ code elements from Doxygen XML output. These directives integrate seamlessly with Sphinx's reStructuredText processing and support extensive customization options.
3

4
## Capabilities
5

6
### Index and File Directives
7

8
Generate comprehensive documentation indexes and document entire files with all their contents.
9

10
```rst { .api }
11
.. doxygenindex::
12
   :project: project_name
13
   :outline:
14
   :no-link:
15

16
.. autodoxygenindex::
17
   :project: project_name
18
   :outline:
19
   :no-link:
20

21
.. doxygenfile:: filename.h
22
   :project: project_name
23
   :sections:
24
   :no-link:
25
   :allow-dot-graphs:
26

27
.. autodoxygenfile:: filename.h
28
   :project: project_name
29
   :sections:
30
   :no-link:
31
   :allow-dot-graphs:
32
```
33

34
**doxygenindex**: Creates a comprehensive index of all documented elements in the project.
35

36
**autodoxygenindex**: Like doxygenindex but automatically generates Doxygen XML first.
37

38
**doxygenfile**: Documents an entire file including all classes, functions, and variables within it.
39

40
**autodoxygenfile**: Like doxygenfile but automatically generates Doxygen XML first.
41

42
### Class and Structure Directives
43

44
Document object-oriented programming constructs including classes, interfaces, structures, and unions.
45

46
```rst { .api }
47
.. doxygenclass:: ClassName
48
   :project: project_name
49
   :path: xml_path
50
   :members:
51
   :membergroups: public,protected
52
   :members-only:
53
   :protected-members:
54
   :private-members:
55
   :undoc-members:
56
   :show: section_name
57
   :outline:
58
   :no-link:
59
   :allow-dot-graphs:
60

61
.. doxygeninterface:: InterfaceName
62
   :project: project_name
63
   :path: xml_path
64
   :members:
65
   :membergroups: public,protected
66
   :members-only:
67
   :protected-members:
68
   :private-members:
69
   :undoc-members:
70
   :show: section_name
71
   :outline:
72
   :no-link:
73
   :allow-dot-graphs:
74

75
.. doxygenstruct:: StructName
76
   :project: project_name
77
   :path: xml_path
78
   :members:
79
   :membergroups: public,protected
80
   :members-only:
81
   :protected-members:
82
   :private-members:
83
   :undoc-members:
84
   :show: section_name
85
   :outline:
86
   :no-link:
87
   :allow-dot-graphs:
88

89
.. doxygenunion:: UnionName
90
   :project: project_name
91
   :path: xml_path
92
   :members:
93
   :membergroups: public,protected
94
   :members-only:
95
   :protected-members:
96
   :private-members:
97
   :undoc-members:
98
   :show: section_name
99
   :outline:
100
   :no-link:
101
   :allow-dot-graphs:
102
```
103

104
**doxygenclass**: Documents C++ classes with full member documentation.
105

106
**doxygeninterface**: Documents interfaces (primarily for languages like C# and Java).
107

108
**doxygenstruct**: Documents C/C++ structures.
109

110
**doxygenunion**: Documents C/C++ unions.
111

112
### Function and Variable Directives
113

114
Document functions, methods, variables, and preprocessor definitions.
115

116
```rst { .api }
117
.. doxygenfunction:: functionName
118
   :project: project_name
119
   :path: xml_path
120
   :outline:
121
   :no-link:
122

123
.. doxygenvariable:: variableName
124
   :project: project_name
125
   :path: xml_path
126
   :outline:
127
   :no-link:
128

129
.. doxygendefine:: MACRO_NAME
130
   :project: project_name
131
   :path: xml_path
132
   :outline:
133
   :no-link:
134
```
135

136
**doxygenfunction**: Documents individual functions or methods, including overloaded functions.
137

138
**doxygenvariable**: Documents global variables and member variables.
139

140
**doxygendefine**: Documents preprocessor macros and #define statements.
141

142
### Type and Concept Directives
143

144
Document type definitions, enumerations, and modern C++ concepts.
145

146
```rst { .api }
147
.. doxygentypedef:: TypedefName
148
   :project: project_name
149
   :path: xml_path
150
   :outline:
151
   :no-link:
152

153
.. doxygenenum:: EnumName
154
   :project: project_name
155
   :path: xml_path
156
   :outline:
157
   :no-link:
158

159
.. doxygenenumvalue:: ENUM_VALUE
160
   :project: project_name
161
   :path: xml_path
162
   :outline:
163
   :no-link:
164

165
.. doxygenconcept:: ConceptName
166
   :project: project_name
167
   :path: xml_path
168
   :outline:
169
   :no-link:
170
```
171

172
**doxygentypedef**: Documents typedef declarations and type aliases.
173

174
**doxygenenum**: Documents enumeration types with their values.
175

176
**doxygenenumvalue**: Documents individual enumeration values.
177

178
**doxygenconcept**: Documents C++20 concepts.
179

180
### Container Directives
181

182
Document logical groupings and organizational structures.
183

184
```rst { .api }
185
.. doxygennamespace:: NamespaceName
186
   :project: project_name
187
   :path: xml_path
188
   :content-only:
189
   :outline:
190
   :no-link:
191

192
.. doxygengroup:: GroupName
193
   :project: project_name
194
   :path: xml_path
195
   :content-only:
196
   :outline:
197
   :no-link:
198
   :inner:
199
   :members:
200
   :membergroups: public,protected
201
   :private-members:
202
   :undoc-members:
203

204
.. doxygenpage:: PageName
205
   :project: project_name
206
   :path: xml_path
207
   :content-only:
208
   :outline:
209
   :no-link:
210
```
211

212
**doxygennamespace**: Documents C++ namespaces and their contents.
213

214
**doxygengroup**: Documents Doxygen groups (logical groupings created with @defgroup).
215

216
**doxygenpage**: Documents Doxygen pages (created with @page commands).
217

218
## Common Directive Options
219

220
### Project Selection Options
221
- `:project:` - Specify which project to use (from breathe_projects config)
222
- `:path:` - Direct path to XML files (alternative to project)
223

224
### Member Control Options  
225
- `:members:` - Include member documentation
226
- `:membergroups:` - Specify which member groups to include (public, protected, private)
227
- `:members-only:` - Show only members, not the container description
228
- `:protected-members:` - Include protected members
229
- `:private-members:` - Include private members  
230
- `:undoc-members:` - Include undocumented members
231

232
### Display Options
233
- `:outline:` - Show only declarations without detailed descriptions
234
- `:no-link:` - Don't create cross-reference links
235
- `:content-only:` - Show only content, not the container
236
- `:sections:` - Include section documentation (for files)
237
- `:show:` - Show specific sections only
238
- `:allow-dot-graphs:` - Allow Graphviz dot graph rendering
239

240
### Group Options (for doxygengroup)
241
- `:inner:` - Include inner groups recursively
242

243
## Usage Examples
244

245
### Basic Class Documentation
246

247
```rst
248
.. doxygenclass:: MyClass
249
   :members:
250
   :private-members:
251
```
252

253
### Function with Specific Project
254

255
```rst
256
.. doxygenfunction:: processData
257
   :project: mylib
258
```
259

260
### Namespace with Custom Sections
261

262
```rst
263
.. doxygennamespace:: math::geometry
264
   :show: public-func,public-type
265
```
266

267
### File Documentation with Sections
268

269
```rst
270
.. doxygenfile:: utility.hpp
271
   :sections:
272
   :allow-dot-graphs:
273
```
274

275
### Group with All Members
276

277
```rst
278
.. doxygengroup:: DataStructures
279
   :members:
280
   :undoc-members:
281
   :inner:
282
```
283

284
## Base Directive Class
285

286
All breathe directives inherit from a common base class:
287

288
```python { .api }
289
class BaseDirective(SphinxDirective):
290
    @property
291
    def directive_args(self) -> list
292
    
293
    @property  
294
    def project_info_factory(self) -> ProjectInfoFactory
295
    
296
    @property
297
    def parser_factory(self) -> DoxygenParserFactory
298
    
299
    @property
300
    def finder_factory(self) -> FinderFactory
301
    
302
    @property
303
    def filter_factory(self) -> FilterFactory
304
    
305
    @property
306
    def kind(self) -> str
307
    
308
    def create_warning(self, project_info: ProjectInfo | None, **kwargs) -> _WarningHandler
309
    
310
    def render(
311
        self, 
312
        node_stack, 
313
        project_info: ProjectInfo, 
314
        filter_: Filter, 
315
        target_handler: TargetHandler, 
316
        mask_factory: MaskFactoryBase, 
317
        directive_args
318
    ) -> list[nodes.Node]
319
```
320

321
The base class provides common functionality for project resolution, XML parsing, filtering, and rendering that all specific directives build upon.
322

323
## Additional Configuration Options
324

325
Beyond the standard directive options, breathe provides additional configuration values that affect directive behavior:
326

327
```python { .api }
328
# File extension handling for implementation files
329
breathe_implementation_filename_extensions = [".c", ".cc", ".cpp"]
330

331
# Member page organization
332
breathe_separate_member_pages = False
333
```
334

335
### breathe_implementation_filename_extensions
336

337
Controls which file extensions are considered implementation files when processing file documentation. This affects how Doxygen processes source code files.
338

339
**Type**: `List[str]`  
340
**Default**: `[".c", ".cc", ".cpp"]`
341

342
### breathe_separate_member_pages
343

344
When enabled, creates separate documentation pages for class/struct members instead of including them inline with the container documentation.
345

346
**Type**: `bool`  
347
**Default**: `False`