0
# CLI Tools
1

2
The numpydoc command-line interface provides tools for rendering and validating NumPy-style docstrings. It supports multiple commands for different use cases, from single object validation to batch file processing.
3

4
## Main CLI Entry Point
5

6
### CLI Function
7

8
```python { .api }
9
def main(argv=None) -> int:
10
    """
11
    CLI entry point, returns exit code.
12
    
13
    Main command-line interface function that parses arguments,
14
    dispatches to appropriate subcommands, and handles errors.
15
    
16
    Parameters
17
    ----------
18
    argv : list of str, optional
19
        Command-line arguments (defaults to sys.argv[1:])
20
        
21
    Returns
22
    -------
23
    int
24
        Exit code (0 for success, non-zero for errors)
25
        
26
    Examples
27
    --------
28
    >>> from numpydoc.cli import main
29
    >>> main(['render', 'numpy.array'])
30
    0
31
    
32
    >>> main(['validate', 'numpy.mean'])  
33
    0
34
    """
35
```
36

37
### Parser Creation
38

39
```python { .api }
40
def get_parser() -> argparse.ArgumentParser:
41
    """
42
    Return argparse.ArgumentParser for CLI.
43
    
44
    Creates and configures the argument parser with all subcommands,
45
    options, and help text for the numpydoc CLI interface.
46
    
47
    Returns
48
    -------
49
    argparse.ArgumentParser
50
        Configured argument parser with subcommands:
51
        - render: Render docstring to reStructuredText
52
        - validate: Validate single object docstring  
53
        - lint: Validate files using AST parsing
54
        
55
    Examples
56
    --------
57
    >>> parser = get_parser()
58
    >>> args = parser.parse_args(['render', 'numpy.array'])
59
    >>> print(args.command)
60
    'render'
61
    >>> print(args.import_path)  
62
    'numpy.array'
63
    """
64
```
65

66
## CLI Commands
67

68
### Render Command
69

70
```python { .api }
71
def render_object(import_path: str, config=None):
72
    """
73
    Test docstring rendering for object.
74
    
75
    Loads the specified object, parses its docstring, and renders
76
    it to reStructuredText format for preview or debugging purposes.
77
    
78
    Parameters
79
    ----------
80
    import_path : str
81
        Dotted import path to object (e.g., 'numpy.array', 'scipy.stats.norm')
82
    config : dict, optional
83
        Configuration dictionary for rendering options
84
        
85
    Examples
86
    --------
87
    >>> render_object('numpy.array')  
88
    # Outputs rendered reStructuredText to stdout
89
    
90
    >>> render_object('mymodule.MyClass.method')
91
    # Renders method docstring with proper formatting
92
    """
93
```
94

95
### Validate Command
96

97
```python { .api }
98
def validate_object(import_path: str):
99
    """
100
    Run validation for object.
101
    
102
    Performs comprehensive docstring validation for the specified
103
    object and reports any validation errors found.
104
    
105
    Parameters
106
    ----------
107
    import_path : str
108
        Dotted import path to object to validate
109
        
110
    Examples
111
    --------  
112
    >>> validate_object('numpy.mean')
113
    # Outputs validation results to stdout
114
    
115
    >>> validate_object('scipy.stats.norm.pdf')  
116
    # Validates specific method docstring
117
    """
118
```
119

120
## Command-Line Usage
121

122
### Render Subcommand
123

124
```bash
125
# Basic rendering
126
numpydoc render numpy.array
127

128
# Render class method  
129
numpydoc render pandas.DataFrame.head
130

131
# Render with custom config
132
numpydoc render --config myconfig.json numpy.fft.fft
133
```
134

135
### Validate Subcommand
136

137
```bash
138
# Validate single function
139
numpydoc validate numpy.mean
140

141
# Validate class
142
numpydoc validate sklearn.linear_model.LinearRegression
143

144
# Validate method
145
numpydoc validate matplotlib.pyplot.plot
146
```
147

148
### Lint Subcommand
149

150
```bash
151
# Validate all functions in a file
152
numpydoc lint src/mymodule.py
153

154
# Validate multiple files
155
numpydoc lint src/*.py
156

157
# Validate with specific config  
158
numpydoc lint --config pyproject.toml src/
159

160
# Exclude certain checks
161
numpydoc lint --ignore GL01,SS01 myfile.py
162
```
163

164
## CLI Arguments and Options
165

166
### Global Options
167

168
```bash
169
numpydoc [global-options] <command> [command-options]
170

171
Global Options:
172
  -h, --help     Show help message and exit
173
  -V, --version  Show program version and exit
174
```
175

176
### Render Options
177

178
```bash
179
numpydoc render [options] <import_path>
180

181
Arguments:
182
  import_path    Dotted path to object (e.g., numpy.array)
183

184
Options:
185
  -c, --config FILE    Configuration file path
186
  -o, --output FILE    Output file (default: stdout)  
187
  --format FORMAT      Output format (rst, html, markdown)
188
```
189

190
### Validate Options  
191

192
```bash
193
numpydoc validate [options] <import_path>
194

195
Arguments:
196
  import_path    Dotted path to object to validate
197

198
Options:
199
  -c, --config FILE    Configuration file path
200
  --checks CODES       Comma-separated validation check codes
201
  --ignore CODES       Comma-separated codes to ignore
202
  --verbose            Show detailed validation information
203
```
204

205
### Lint Options
206

207
```bash  
208
numpydoc lint [options] <files...>
209

210
Arguments:
211
  files...       Python source files to validate
212

213
Options:
214
  -c, --config FILE    Configuration file (pyproject.toml, setup.cfg)
215
  --checks CODES       Comma-separated validation check codes  
216
  --ignore CODES       Comma-separated codes to ignore
217
  --exclude PATTERNS   File patterns to exclude from validation
218
  --verbose            Show detailed output
219
  --quiet              Suppress output except errors
220
```
221

222
## Configuration
223

224
### Configuration Files
225

226
numpydoc CLI supports configuration through multiple file formats:
227

228
#### pyproject.toml
229
```toml
230
[tool.numpydoc_validation]
231
checks = ["all", "GL08"]
232
ignore = ["GL01", "SS01"] 
233
exclude = [
234
    "tests/.*",
235
    ".*/_private.py"
236
]
237

238
override = {"mymodule.legacy_func" = {"all" = false}}
239
```
240

241
#### setup.cfg
242
```ini
243
[numpydoc_validation]  
244
checks = all,GL08
245
ignore = GL01,SS01
246
exclude = tests/.*,.*/_private.py
247
```
248

249
#### JSON Configuration
250
```json
251
{
252
  "checks": ["all", "GL08"],
253
  "ignore": ["GL01", "SS01"],
254
  "exclude": ["tests/.*", ".*/_private.py"],
255
  "override": {
256
    "mymodule.legacy_func": {"all": false}
257
  }
258
}
259
```
260

261
## Exit Codes
262

263
The CLI returns different exit codes based on operation results:
264

265
- **0**: Success (no errors found)
266
- **1**: Validation errors found  
267
- **2**: Command-line argument errors
268
- **3**: Import/module loading errors
269
- **4**: Configuration file errors
270

271
## Usage Examples
272

273
### Basic Object Rendering
274

275
```bash
276
# Render numpy array docstring
277
$ numpydoc render numpy.array
278
Create an array.
279

280
Parameters
281
----------
282
object : array_like
283
    An array, any object exposing the array interface...
284
    
285
Returns  
286
-------
287
out : ndarray
288
    An array object satisfying the specified requirements.
289
```
290

291
### Validation with Custom Checks
292

293
```bash  
294
# Validate with specific checks
295
$ numpydoc validate --checks GL01,SS01,PR01 mymodule.func
296
GL01: Docstring text (summary) should start in the line immediately after the opening quotes
297
PR01: Parameters {'x'} not documented
298

299
# Ignore certain validation errors
300
$ numpydoc validate --ignore GL08 mymodule.func
301
```
302

303
### Batch File Validation
304

305
```bash
306
# Validate all Python files in src/
307
$ numpydoc lint src/
308
src/module1.py:15: GL01: Docstring text should start immediately after quotes
309
src/module2.py:42: PR01: Parameters {'param'} not documented  
310
src/module3.py:89: RT01: No Returns section found
311

312
Found 3 validation errors in 3 files.
313

314
# Validate with configuration file
315
$ numpydoc lint --config pyproject.toml src/
316
Using configuration from pyproject.toml
317
Checking 15 files...
318
All docstrings valid!
319
```
320

321
### Integration with Pre-commit
322

323
```yaml
324
# .pre-commit-config.yaml
325
repos:
326
  - repo: local
327
    hooks:
328
      - id: numpydoc-validation
329
        name: numpydoc docstring validation
330
        entry: numpydoc lint
331
        language: system
332
        files: \.py$
333
        args: ['--config', 'pyproject.toml']
334
```
335

336
### Programmatic Usage
337

338
```python
339
from numpydoc.cli import main, render_object, validate_object
340

341
# Use CLI functions programmatically
342
exit_code = main(['validate', 'numpy.array'])
343
print(f"Validation exit code: {exit_code}")
344

345
# Direct function calls
346
render_object('scipy.stats.norm')
347
validate_object('pandas.DataFrame.head')
348

349
# Custom configuration
350
config = {'validation_checks': {'GL01', 'SS01'}}  
351
render_object('mymodule.func', config=config)
352
```