0
# Command Line Interface
1
2
The breathe-apidoc command provides batch generation of reStructuredText files from Doxygen XML output. It processes an entire Doxygen XML tree and creates individual .rst files with breathe directives for each documented element.
3
4
## Capabilities
5
6
### Main Command
7
8
Generate reStructuredText files with breathe directives from Doxygen XML.
9
10
```bash { .api }
11
breathe-apidoc [options] <rootpath>
12
```
13
14
**rootpath**: Required path to directory containing Doxygen's index.xml file.
15
16
### Command Options
17
18
Control output generation, file handling, and content inclusion.
19
20
```bash { .api }
21
# Required options
22
-o OUTPUT_DIR, --output-dir OUTPUT_DIR Directory to place all output
23
24
# File handling options
25
-f, --force Overwrite existing files
26
-n, --dry-run Run without creating files
27
-T, --no-toc Don't create table of contents
28
-s SUFFIX, --suffix SUFFIX File suffix (default: rst)
29
30
# Content options
31
-m, --members Include members for applicable types
32
-p PROJECT, --project PROJECT Project name for generated directives
33
-g TYPES, --generate TYPES Types to generate (comma-separated)
34
35
# Output options
36
-q, --quiet Suppress informational messages
37
--version Show version information
38
```
39
40
### Supported Types
41
42
Types that can be generated with the `-g/--generate` option:
43
44
```python { .api }
45
TYPEDICT = {
46
"class": "Class",
47
"interface": "Interface",
48
"struct": "Struct",
49
"union": "Union",
50
"file": "File",
51
"namespace": "Namespace",
52
"group": "Group"
53
}
54
```
55
56
**Types supporting :members: option**: `class`, `group`, `interface`, `namespace`, `struct`
57
58
### Core Functions
59
60
Functions that power the breathe-apidoc command:
61
62
```python { .api }
63
def main() -> None
64
"""Main entry point for breathe-apidoc command."""
65
66
def recurse_tree(args) -> None
67
"""Process entire Doxygen XML tree and create corresponding files."""
68
69
def create_package_file(package: str, package_type: str, package_id: str, args) -> None
70
"""Build and write individual package documentation files."""
71
72
def create_modules_toc_file(key: str, value: str, args) -> None
73
"""Create table of contents files for each type."""
74
75
def write_file(name: str, text: str, args) -> None
76
"""Write output file with specified name and content."""
77
78
def format_directive(package_type: str, package: str, args) -> str
79
"""Create breathe directive with appropriate options."""
80
81
def format_heading(level: int, text: str) -> str
82
"""Create reStructuredText heading of specified level."""
83
```
84
85
## Usage Examples
86
87
### Basic API Documentation Generation
88
89
Generate documentation for all supported types:
90
91
```bash
92
breathe-apidoc -o docs/api -f /path/to/doxygen/xml
93
```
94
95
### Generate Specific Types Only
96
97
Generate only classes and namespaces:
98
99
```bash
100
breathe-apidoc -o docs/api -g class,namespace /path/to/doxygen/xml
101
```
102
103
### Include Members with Project Name
104
105
Generate with member documentation and project specification:
106
107
```bash
108
breathe-apidoc -o docs/api -m -p myproject /path/to/doxygen/xml
109
```
110
111
### Dry Run to Preview Output
112
113
See what would be generated without creating files:
114
115
```bash
116
breathe-apidoc -o docs/api -n -m /path/to/doxygen/xml
117
```
118
119
### Custom File Extension
120
121
Generate .txt files instead of .rst:
122
123
```bash
124
breathe-apidoc -o docs/api -s txt /path/to/doxygen/xml
125
```
126
127
### Quiet Mode with No Table of Contents
128
129
Generate silently without TOC files:
130
131
```bash
132
breathe-apidoc -o docs/api -q -T /path/to/doxygen/xml
133
```
134
135
## Output Structure
136
137
The command creates a structured directory layout:
138
139
```
140
output_dir/
141
├── class/
142
│ ├── MyClass_8cpp.rst # Individual class files
143
│ └── AnotherClass_8cpp.rst
144
├── namespace/
145
│ ├── MyNamespace.rst # Individual namespace files
146
│ └── AnotherNamespace.rst
147
├── file/
148
│ ├── header_8h.rst # Individual file documentation
149
│ └── source_8cpp.rst
150
├── classlist.rst # Table of contents for classes
151
├── namespacelist.rst # Table of contents for namespaces
152
└── filelist.rst # Table of contents for files
153
```
154
155
## Generated File Format
156
157
Each generated file contains:
158
159
### File Header
160
ReStructuredText heading with element type and name.
161
162
### Breathe Directive
163
Appropriate directive (doxygenclass, doxygennamespace, etc.) with:
164
- `:project:` option if specified
165
- `:members:` option for applicable types if `-m` flag used
166
167
### Example Generated Class File
168
169
```rst
170
Class MyClass
171
=============
172
173
.. doxygenclass:: MyClass
174
:project: myproject
175
:members:
176
```
177
178
### Example Generated Table of Contents
179
180
```rst
181
Class list
182
==========
183
184
.. toctree::
185
:glob:
186
187
class/*
188
```
189
190
## Integration with Sphinx
191
192
The generated files integrate seamlessly with Sphinx documentation:
193
194
1. **Include in toctree**: Add generated list files to your main toctree
195
2. **Configure breathe**: Ensure breathe_projects matches project names used
196
3. **Build documentation**: Run `sphinx-build` as normal
197
198
### Example Integration
199
200
```rst
201
.. toctree::
202
:maxdepth: 2
203
204
api/classlist
205
api/namespacelist
206
api/filelist
207
```
208
209
## Error Handling
210
211
The command validates inputs and provides clear error messages:
212
213
- Checks that rootpath is a valid directory
214
- Verifies index.xml exists in rootpath
215
- Creates output directory if it doesn't exist
216
- Validates generate types against supported options
217
- Handles file writing permissions and conflicts
218
219
Common error scenarios:
220
- Missing index.xml file
221
- Invalid rootpath directory
222
- Permission denied for output directory
223
- Invalid type specified in --generate option