0
# Command Line Interface
1
2
Complete command-line tool for generating API documentation from API Extractor JSON files. Supports multiple output formats including Markdown, YAML for DocFX, and experimental config-driven generation.
3
4
## Capabilities
5
6
### Markdown Action
7
8
Generates Markdown documentation files from API Extractor JSON files.
9
10
```bash { .api }
11
api-documenter markdown --input-folder <path> --output-folder <path>
12
```
13
14
**Parameters:**
15
- `--input-folder, -i` (required): Directory containing *.api.json files from API Extractor
16
- `--output-folder, -o` (required): Directory where markdown files will be generated
17
18
**Usage Example:**
19
20
```bash
21
# Generate markdown docs
22
api-documenter markdown --input-folder ./temp --output-folder ./docs
23
24
# Using short flags
25
api-documenter markdown -i ./temp -o ./docs
26
```
27
28
### YAML Action
29
30
Generates YAML documentation files compatible with DocFX and Office Add-ins documentation systems.
31
32
```bash { .api }
33
api-documenter yaml --input-folder <path> --output-folder <path> [--office] [--new-docfx-namespaces] [--yaml-format <format>]
34
```
35
36
**Parameters:**
37
- `--input-folder, -i` (required): Directory containing *.api.json files from API Extractor
38
- `--output-folder, -o` (required): Directory where YAML files will be generated
39
- `--office` (optional): Enable Office Add-ins specific features and formatting
40
- `--new-docfx-namespaces` (optional): Enable experimental DocFX namespace support
41
- `--yaml-format` (optional): Output format, either 'udp' or 'sdp' (default: 'sdp')
42
43
**Usage Examples:**
44
45
```bash
46
# Basic YAML generation
47
api-documenter yaml --input-folder ./temp --output-folder ./yaml-docs
48
49
# Office Add-ins specific YAML
50
api-documenter yaml -i ./temp -o ./office-docs --office
51
52
# DocFX with experimental namespaces
53
api-documenter yaml -i ./temp -o ./docfx-docs --new-docfx-namespaces
54
55
# Specify YAML format
56
api-documenter yaml -i ./temp -o ./docs --yaml-format udp
57
```
58
59
### Generate Action
60
61
Experimental configuration-driven documentation generation that uses a config file to determine output format and options.
62
63
```bash { .api }
64
api-documenter generate --input-folder <path> --output-folder <path>
65
```
66
67
**Parameters:**
68
- `--input-folder, -i` (required): Directory containing *.api.json files from API Extractor
69
- `--output-folder, -o` (required): Directory where documentation files will be generated
70
71
**Requirements:**
72
- Must have an `api-documenter.json` configuration file in the current directory
73
74
**Usage Example:**
75
76
```bash
77
# Config-driven generation (requires api-documenter.json)
78
api-documenter generate --input-folder ./temp --output-folder ./docs
79
```
80
81
## Configuration File
82
83
For the `generate` action, create an `api-documenter.json` configuration file:
84
85
```json { .api }
86
{
87
"configFormatVersion": "1.0",
88
"outputTargets": [
89
{
90
"outputFormat": "markdown"
91
}
92
],
93
"newlineKind": "lf",
94
"plugins": [
95
{
96
"packageName": "my-documenter-plugin",
97
"enabled": true
98
}
99
],
100
"tableOfContents": {
101
"catchAllCategory": "Other"
102
}
103
}
104
```
105
106
## Programmatic CLI Usage
107
108
```typescript { .api }
109
import { ApiDocumenterCommandLine } from "@microsoft/api-documenter/lib/cli/ApiDocumenterCommandLine";
110
111
const commandLine = new ApiDocumenterCommandLine();
112
commandLine.executeAsync().catch(console.error);
113
```
114
115
## CLI Classes
116
117
### ApiDocumenterCommandLine
118
119
Main command line parser that orchestrates all available actions.
120
121
```typescript { .api }
122
class ApiDocumenterCommandLine extends CommandLineParser {
123
constructor();
124
}
125
```
126
127
### BaseAction
128
129
Abstract base class for all CLI actions providing common functionality including API model loading and folder management.
130
131
```typescript { .api }
132
abstract class BaseAction extends CommandLineAction {
133
/**
134
* Creates a new BaseAction instance
135
* @param options - Command line action configuration options
136
*/
137
protected constructor(options: ICommandLineActionOptions);
138
139
/**
140
* Builds the API model from input files and validates folders
141
* @returns API model with input/output folder paths
142
*/
143
protected buildApiModel(): IBuildApiModelResult;
144
}
145
146
interface IBuildApiModelResult {
147
/**
148
* The loaded API model containing all packages from *.api.json files
149
*/
150
apiModel: ApiModel;
151
152
/**
153
* Input folder path containing the *.api.json files
154
*/
155
inputFolder: string;
156
157
/**
158
* Output folder path where documentation will be written
159
*/
160
outputFolder: string;
161
}
162
```
163
164
### MarkdownAction
165
166
CLI action implementation for markdown documentation generation.
167
168
```typescript { .api }
169
class MarkdownAction extends BaseAction {
170
constructor(parser: CommandLineParser);
171
}
172
```
173
174
### YamlAction
175
176
CLI action implementation for YAML documentation generation with DocFX and Office support.
177
178
```typescript { .api }
179
class YamlAction extends BaseAction {
180
constructor(parser: CommandLineParser);
181
}
182
```
183
184
### GenerateAction
185
186
Experimental CLI action for config-driven documentation generation.
187
188
```typescript { .api }
189
class GenerateAction extends BaseAction {
190
constructor(parser: CommandLineParser);
191
}
192
```
193
194
## Error Handling
195
196
The CLI tool provides detailed error messages for common issues:
197
198
- **Missing input folder**: Clear message when API Extractor files are not found
199
- **Configuration errors**: Detailed validation messages for malformed config files
200
- **Plugin loading errors**: Specific error information when plugins fail to load
201
- **File system errors**: Informative messages for permission and disk space issues
202
203
All CLI actions return appropriate exit codes (0 for success, non-zero for errors) for use in build scripts and CI/CD pipelines.