0
# Command Line Interface
1

2
pdoc's command-line interface for generating documentation from Python modules. The CLI provides comprehensive options for customizing documentation output and development workflows.
3

4
## Capabilities
5

6
### Main CLI Function
7

8
Entry point for command-line usage with argument parsing and configuration.
9

10
```python { .api }
11
def cli(args: list[str] | None = None) -> None:
12
    """
13
    Command-line interface entry point.
14
    
15
    Parameters:
16
    - args: list[str] | None - Command line arguments (uses sys.argv if None)
17
    
18
    Features:
19
    - Argument parsing and validation
20
    - Rendering configuration
21
    - Output directory or web server mode
22
    - Error handling and user feedback
23
    """
24
```
25

26
### Version Information
27

28
Utility for displaying version information including development builds.
29

30
```python { .api }
31
def get_dev_version() -> str:
32
    """
33
    Return detailed version string with git information for development builds.
34
    
35
    Returns:
36
    - str: Version string with git commit hash if available
37
    """
38
```
39

40
## Command Line Usage
41

42
### Basic Documentation Generation
43

44
```bash
45
# Generate documentation for a module
46
pdoc my_module
47

48
# Generate documentation for a Python file
49
pdoc ./my_script.py
50

51
# Generate documentation for multiple modules
52
pdoc module1 module2 module3
53

54
# Exclude submodules using negative patterns
55
pdoc my_package !my_package.internal
56
```
57

58
### Output Options
59

60
```bash
61
# Save documentation to HTML files
62
pdoc my_module -o ./docs
63

64
# Save to specific directory with custom name
65
pdoc my_module --output-directory ./api-docs
66

67
# Generate documentation without starting web server
68
pdoc my_module -o ./output
69
```
70

71
### Development Server
72

73
```bash
74
# Start development server (default: localhost:8080)
75
pdoc my_module
76

77
# Custom host and port
78
pdoc my_module --host 0.0.0.0 --port 3000
79

80
# Bind to all interfaces
81
pdoc my_module --host 0.0.0.0
82
```
83

84
### Docstring Format Options
85

86
```bash
87
# Use Google-style docstring format
88
pdoc my_module --docformat google
89

90
# Use NumPy-style docstring format  
91
pdoc my_module --docformat numpy
92

93
# Use reStructuredText format (default)
94
pdoc my_module --docformat restructuredtext
95

96
# Use plain Markdown
97
pdoc my_module --docformat markdown
98
```
99

100
### Rendering Customization
101

102
```bash
103
# Include undocumented members
104
pdoc my_module --include-undocumented
105

106
# Hide undocumented members
107
pdoc my_module --no-include-undocumented
108

109
# Show source code links
110
pdoc my_module --show-source
111

112
# Hide source code links
113
pdoc my_module --no-show-source
114

115
# Enable math formula rendering
116
pdoc my_module --math
117

118
# Enable Mermaid diagram rendering
119
pdoc my_module --mermaid
120

121
# Disable search functionality
122
pdoc my_module --no-search
123
```
124

125
### Template and Styling
126

127
```bash
128
# Use custom template directory
129
pdoc my_module --template-directory ./custom_templates
130

131
# Add project logo
132
pdoc my_module --logo "https://example.com/logo.png"
133

134
# Logo with custom link
135
pdoc my_module --logo "logo.png" --logo-link "https://example.com"
136

137
# Custom favicon
138
pdoc my_module --favicon "favicon.ico"
139

140
# Custom footer text
141
pdoc my_module --footer-text "© 2024 My Project"
142
```
143

144
### Edit Links
145

146
```bash
147
# Add edit links to GitHub
148
pdoc my_module --edit-url my_module=https://github.com/user/repo/blob/main/my_module/
149

150
# Multiple edit URL mappings
151
pdoc my_module other_module \
152
  --edit-url my_module=https://github.com/user/repo1/blob/main/my_module/ \
153
  --edit-url other_module=https://github.com/user/repo2/blob/main/other_module/
154
```
155

156
### Version and Help
157

158
```bash
159
# Show version information
160
pdoc --version
161

162
# Show help message
163
pdoc --help
164

165
# Show detailed help for all options
166
pdoc -h
167
```
168

169
## Advanced Usage Examples
170

171
### Production Documentation Build
172

173
```bash
174
#!/bin/bash
175
# Generate production documentation
176

177
pdoc my_package \
178
  --output-directory ./docs \
179
  --docformat google \
180
  --no-show-source \
181
  --logo "https://my-site.com/logo.png" \
182
  --logo-link "https://my-site.com" \
183
  --footer-text "© 2024 My Company" \
184
  --favicon "https://my-site.com/favicon.ico" \
185
  --edit-url my_package=https://github.com/mycompany/my_package/blob/main/my_package/
186
```
187

188
### Development Server with All Features
189

190
```bash
191
pdoc my_package \
192
  --host localhost \
193
  --port 8080 \
194
  --docformat google \
195
  --show-source \
196
  --math \
197
  --mermaid \
198
  --template-directory ./dev_templates \
199
  --logo "./assets/dev-logo.png"
200
```
201

202
### Multi-Package Documentation
203

204
```bash
205
# Document multiple related packages together
206
pdoc core_package utils_package plugins_package \
207
  --output-directory ./complete_docs \
208
  --docformat numpy \
209
  --math \
210
  --edit-url core_package=https://github.com/org/core/blob/main/core_package/ \
211
  --edit-url utils_package=https://github.com/org/utils/blob/main/utils_package/ \
212
  --edit-url plugins_package=https://github.com/org/plugins/blob/main/plugins_package/
213
```
214

215
### Custom Template Development
216

217
```bash
218
# Serve with custom templates for development
219
pdoc my_package \
220
  --template-directory ./custom_templates \
221
  --host localhost \
222
  --port 3000 \
223
  --show-source \
224
  --footer-text "Custom Template Development"
225
```
226

227
### CI/CD Integration
228

229
```bash
230
#!/bin/bash
231
# CI script for documentation generation
232

233
set -e
234

235
echo "Generating API documentation..."
236

237
pdoc my_package \
238
  --output-directory ./dist/docs \
239
  --docformat google \
240
  --no-show-source \
241
  --logo "$LOGO_URL" \
242
  --logo-link "$PROJECT_URL" \
243
  --footer-text "Built on $(date)" \
244
  --edit-url my_package="$REPO_URL/blob/$BRANCH_NAME/my_package/"
245

246
echo "Documentation generated successfully!"
247
```
248

249
### Debugging and Development
250

251
```bash
252
# Generate with maximum verbosity for debugging
253
pdoc my_module \
254
  --include-undocumented \
255
  --show-source \
256
  --docformat restructuredtext \
257
  --template-directory ./debug_templates
258

259
# Test different docstring formats
260
pdoc my_module --docformat google    # Test Google style
261
pdoc my_module --docformat numpy     # Test NumPy style  
262
pdoc my_module --docformat markdown  # Test Markdown
263
```
264

265
## Integration Examples
266

267
### Makefile Integration
268

269
```makefile
270
# Makefile targets for documentation
271

272
.PHONY: docs docs-serve docs-clean
273

274
docs:
275
	pdoc my_package -o ./docs --docformat google --logo ./assets/logo.png
276

277
docs-serve:
278
	pdoc my_package --host localhost --port 8080 --docformat google --show-source
279

280
docs-clean:
281
	rm -rf ./docs
282
```
283

284
### npm scripts Integration
285

286
```json
287
{
288
  "scripts": {
289
    "docs": "pdoc my_package -o ./docs --docformat google",
290
    "docs:serve": "pdoc my_package --host localhost --port 8080",
291
    "docs:clean": "rm -rf ./docs"
292
  }
293
}
294
```
295

296
### GitHub Actions
297

298
```yaml
299
name: Generate Documentation
300

301
on:
302
  push:
303
    branches: [ main ]
304

305
jobs:
306
  docs:
307
    runs-on: ubuntu-latest
308
    steps:
309
      - uses: actions/checkout@v3
310
      
311
      - name: Set up Python
312
        uses: actions/setup-python@v4
313
        with:
314
          python-version: '3.11'
315
          
316
      - name: Install dependencies
317
        run: |
318
          pip install pdoc
319
          pip install -e .
320
          
321
      - name: Generate documentation
322
        run: |
323
          pdoc my_package \
324
            --output-directory ./docs \
325
            --docformat google \
326
            --logo "https://my-site.com/logo.png" \
327
            --edit-url my_package=https://github.com/${{ github.repository }}/blob/main/my_package/
328
            
329
      - name: Deploy to GitHub Pages
330
        uses: peaceiris/actions-gh-pages@v3
331
        with:
332
          github_token: ${{ secrets.GITHUB_TOKEN }}
333
          publish_dir: ./docs
334
```
335

336
## Error Handling
337

338
### Common Issues and Solutions
339

340
**Module not found:**
341
```bash
342
# Make sure module is installed or use file path
343
pdoc ./path/to/module.py
344
```
345

346
**Import errors:**
347
```bash
348
# Install missing dependencies first
349
pip install -r requirements.txt
350
pdoc my_module
351
```
352

353
**Template errors:**
354
```bash
355
# Check template directory exists and is readable
356
pdoc my_module --template-directory ./templates
357
```
358

359
**Port conflicts:**
360
```bash
361
# Use different port or let pdoc choose automatically
362
pdoc my_module --port 0  # Auto-select available port
363
```
364

365
### Debug Output
366

367
pdoc provides helpful error messages and warnings for common issues:
368

369
- Missing modules or import failures
370
- Template rendering errors  
371
- File permission problems
372
- Invalid command line arguments
373
- Port binding failures
374

375
Most errors include suggestions for resolution and links to relevant documentation.