0
# CLI Interface
1

2
Comprehensive command-line interface providing extensive options for documentation generation, development servers, project bootstrapping, and workflow automation.
3

4
## Capabilities
5

6
### RenderSession Class
7

8
Helper class that orchestrates CLI rendering sessions, managing configuration loading, overrides, and execution phases.
9

10
```python { .api }
11
class RenderSession:
12
    """
13
    Helper class for CLI rendering sessions that handles configuration loading,
14
    applying overrides, and managing the rendering workflow.
15
    
16
    Attributes:
17
        config: Configuration object or file path
18
        render_toc: Override render_toc option in MarkdownRenderer  
19
        search_path: Override search path in Python loader
20
        modules: Override modules in Python loader
21
        packages: Override packages in Python loader
22
        py2: Override Python 2 compatibility in Python loader
23
    """
24
    
25
    def __init__(
26
        self,
27
        config: Union[None, dict, str],
28
        render_toc: Optional[bool] = None,
29
        search_path: Optional[List[str]] = None,
30
        modules: Optional[List[str]] = None,
31
        packages: Optional[List[str]] = None,
32
        py2: Optional[bool] = None
33
    ):
34
        """
35
        Initialize render session with configuration and overrides.
36
        
37
        Args:
38
            config: Configuration dictionary or path to config file
39
            render_toc: Override table of contents rendering
40
            search_path: Override module search paths
41
            modules: Override specific modules to document
42
            packages: Override specific packages to document  
43
            py2: Override Python 2 compatibility mode
44
        """
45
    
46
    def load(self) -> PydocMarkdown:
47
        """
48
        Load configuration and apply overrides.
49
        
50
        Returns:
51
            Configured PydocMarkdown instance
52
        """
53
    
54
    def render(self, config: PydocMarkdown) -> List[str]:
55
        """
56
        Execute rendering process and return list of files to watch.
57
        
58
        Args:
59
            config: PydocMarkdown configuration
60
            
61
        Returns:
62
            List of file paths that should be watched for changes
63
        """
64
    
65
    def build(self, config: PydocMarkdown, site_dir: str) -> None:
66
        """
67
        Execute build process for renderers that support building.
68
        
69
        Args:
70
            config: PydocMarkdown configuration
71
            site_dir: Directory for build output
72
        """
73
    
74
    def run_server(self, config: PydocMarkdown, open_browser: bool = False):
75
        """
76
        Start development server with file watching and auto-reload.
77
        
78
        Args:
79
            config: PydocMarkdown configuration
80
            open_browser: Whether to automatically open browser
81
        """
82
```
83

84
### CLI Command Function
85

86
Main CLI entry point that handles argument parsing, validation, and execution coordination.
87

88
```python { .api }
89
def cli() -> None:
90
    """
91
    Main CLI command entry point for pydoc-markdown.
92
    
93
    Available as 'pydoc-markdown' command after installation.
94
    Handles all CLI arguments, validation, and execution coordination.
95
    """
96
```
97

98
### Utility Functions
99

100
```python { .api }
101
def error(*args) -> NoReturn:
102
    """
103
    Print error message and exit with status 1.
104
    
105
    Args:
106
        *args: Error message components to print
107
    """
108
```
109

110
## CLI Usage Examples
111

112
### Basic Usage
113

114
```bash
115
# Generate docs with default configuration
116
pydoc-markdown
117

118
# Generate docs from specific config file
119
pydoc-markdown pydoc-markdown.yml
120

121
# Generate docs from inline YAML
122
pydoc-markdown '
123
loaders:
124
  - type: python
125
    modules: [mypackage]
126
renderer:
127
  type: markdown
128
  filename: api.md
129
'
130
```
131

132
### Module and Package Options
133

134
```bash
135
# Document specific modules
136
pydoc-markdown -m mypackage.core -m mypackage.utils
137

138
# Document entire packages
139
pydoc-markdown -p mypackage -p otherpkg
140

141
# Document with custom search paths
142
pydoc-markdown -m mypackage -I src/ -I lib/
143

144
# Mix modules and packages
145
pydoc-markdown -m mypackage.core -p mypackage.plugins
146
```
147

148
### Rendering Options
149

150
```bash
151
# Enable table of contents
152
pydoc-markdown --render-toc
153

154
# Disable table of contents  
155
pydoc-markdown --no-render-toc
156

157
# Python 2 compatibility mode
158
pydoc-markdown --py2 -m legacy_package
159

160
# Modern Python 3 mode (default)
161
pydoc-markdown --py3 -m modern_package
162
```
163

164
### Development Server
165

166
```bash
167
# Start development server (MkDocs/Hugo renderers)
168
pydoc-markdown --server
169

170
# Start server and open browser
171
pydoc-markdown --server --open
172

173
# Server with custom configuration
174
pydoc-markdown -c mkdocs-config.yml --server --open
175
```
176

177
### Building
178

179
```bash
180
# Build final output (after rendering)
181
pydoc-markdown --build
182

183
# Build to custom directory
184
pydoc-markdown --build --site-dir /var/www/docs/
185

186
# Cannot use server and build together
187
# pydoc-markdown --server --build  # ERROR
188
```
189

190
### Project Bootstrapping
191

192
```bash
193
# Create basic configuration
194
pydoc-markdown --bootstrap base
195

196
# Create MkDocs configuration
197
pydoc-markdown --bootstrap mkdocs
198

199
# Create Hugo configuration  
200
pydoc-markdown --bootstrap hugo
201

202
# Create Docusaurus configuration
203
pydoc-markdown --bootstrap docusaurus
204

205
# Create Read the Docs configuration
206
pydoc-markdown --bootstrap readthedocs
207
```
208

209
### Debug and Analysis
210

211
```bash
212
# Dump parsed modules as JSON
213
pydoc-markdown --dump -m mypackage
214

215
# Dump without running processors
216
pydoc-markdown --dump --without-processors -m mypackage
217

218
# Dump with processors (default)
219
pydoc-markdown --dump --with-processors -m mypackage
220

221
# Increase verbosity
222
pydoc-markdown -v   # Info level
223
pydoc-markdown -vv  # Debug level
224

225
# Decrease verbosity
226
pydoc-markdown -q   # Error level only
227
pydoc-markdown -qq  # Critical level only
228
```
229

230
## Configuration File Discovery
231

232
When no config file is specified, pydoc-markdown searches for configuration files in this order:
233

234
1. `pydoc-markdown.yml`
235
2. `pydoc-markdown.yaml`  
236
3. `pyproject.toml` (looks for `[tool.pydoc-markdown]` section)
237

238
```bash
239
# Uses automatic discovery
240
pydoc-markdown
241

242
# Explicit config file
243
pydoc-markdown pydoc-markdown.yml
244
pydoc-markdown custom-config.yaml
245
pydoc-markdown pyproject.toml
246
```
247

248
## Complete CLI Options
249

250
### Arguments
251

252
- `config` (optional): Configuration file path or inline YAML/JSON
253

254
### Options
255

256
**General:**
257
- `--version`: Show version and exit
258
- `--verbose, -v`: Increase log verbosity (can be repeated: `-vv`)
259
- `--quiet, -q`: Decrease log verbosity (can be repeated: `-qq`)
260

261
**Module Selection:**
262
- `--module, -m MODULE`: Module to document (can be repeated)
263
- `--package, -p PACKAGE`: Package to document recursively (can be repeated) 
264
- `--search-path, -I PATH`: Module search directory (can be repeated)
265
- `--py2/--py3`: Python 2/3 compatibility mode
266

267
**Rendering:**
268
- `--render-toc/--no-render-toc`: Enable/disable table of contents
269
- `--server, -s`: Start development server
270
- `--open, -o`: Open browser with server (requires `--server`)
271
- `--build`: Build final output after rendering
272
- `--site-dir DIR`: Build output directory (requires `--build`)
273

274
**Analysis:**
275
- `--dump`: Output parsed modules as JSON
276
- `--with-processors/--without-processors`: Include/exclude processors (with `--dump`)
277

278
**Bootstrapping:**
279
- `--bootstrap TYPE`: Create configuration files
280
  - `base`: Basic configuration
281
  - `mkdocs`: MkDocs integration
282
  - `hugo`: Hugo integration  
283
  - `docusaurus`: Docusaurus integration
284
  - `readthedocs`: Read the Docs setup
285

286
## Examples by Use Case
287

288
### Quick Documentation Generation
289

290
```bash
291
# Document current package  
292
pydoc-markdown -p .
293

294
# Document with custom output
295
pydoc-markdown -p mypackage > api-docs.md
296

297
# Document specific modules only
298
pydoc-markdown -m mypackage.api -m mypackage.client
299
```
300

301
### MkDocs Workflow
302

303
```bash
304
# Bootstrap MkDocs configuration
305
pydoc-markdown --bootstrap mkdocs
306

307
# Start development server
308
pydoc-markdown --server --open
309

310
# Build for production
311
pydoc-markdown --build --site-dir ../docs-site/
312
```
313

314
### Hugo Workflow
315

316
```bash
317
# Bootstrap Hugo configuration
318
pydoc-markdown --bootstrap hugo
319

320
# Development with live reload
321
pydoc-markdown --server
322

323
# Production build
324
pydoc-markdown --build
325
```
326

327
### Debug and Analysis Workflow
328

329
```bash
330
# See what modules would be loaded
331
pydoc-markdown --dump --without-processors -p mypackage
332

333
# Analyze processing results
334
pydoc-markdown --dump -p mypackage | jq '.modules[].name'
335

336
# Debug with verbose output
337
pydoc-markdown -vv -p mypackage
338
```
339

340
### Integration Examples
341

342
```bash
343
# CI/CD pipeline
344
pydoc-markdown --build --site-dir docs/
345
cp -r docs/ /var/www/html/
346

347
# Pre-commit hook
348
pydoc-markdown --dump > /dev/null || exit 1
349

350
# Development workflow with watch
351
pydoc-markdown --server --open &
352
# Make code changes...
353
# Server auto-reloads
354
```