0
# Click Domain
1
2
Specialized Sphinx domain for documenting Click command-line applications. Provides directives that enable interactive command examples with automatic input/output capture, making it easy to create comprehensive CLI documentation.
3
4
## Capabilities
5
6
### Domain Registration
7
8
The Click domain is automatically registered when the extension loads and Click is available.
9
10
```python { .api }
11
def setup(app):
12
"""
13
Register Click domain if Click is installed.
14
15
Conditionally loads the Click domain functionality only when the
16
Click library is available in the environment.
17
18
Parameters:
19
- app: Sphinx application instance
20
"""
21
```
22
23
### Example Declaration
24
25
Directive for defining Click commands and preparing them for execution in documentation.
26
27
```python { .api }
28
# RST directive usage:
29
# .. click:example::
30
#
31
# import click
32
#
33
# @click.command()
34
# @click.option('--name', default='World')
35
# def hello(name):
36
# click.echo(f'Hello {name}!')
37
```
38
39
### Example Execution
40
41
Directive for running Click commands and displaying their input/output in documentation.
42
43
```python { .api }
44
# RST directive usage:
45
# .. click:run::
46
#
47
# invoke(hello, ['--name', 'Documentation'])
48
# println("Custom output line")
49
```
50
51
## Domain Classes
52
53
### ExampleRunner
54
55
Enhanced Click test runner that captures command execution for documentation display.
56
57
```python { .api }
58
class ExampleRunner(CliRunner):
59
"""
60
Click command runner for documentation examples.
61
62
Extends Click's CliRunner to capture and format command execution
63
for display in Sphinx documentation with proper input/output formatting.
64
"""
65
66
def __init__(self):
67
"""Initialize runner with Click namespace and stdin echoing."""
68
69
def invoke(self, cli, args=None, prog_name=None, input=None,
70
terminate_input=False, env=None, _output_lines=None, **extra):
71
"""
72
Execute Click command with output capture.
73
74
Parameters:
75
- cli: Click command or group to execute
76
- args: List of command arguments
77
- prog_name: Program name to display (defaults to cli.name)
78
- input: Input to provide to command (string or list of strings)
79
- terminate_input: Whether to add EOF marker (^D) after input
80
- env: Environment variables to set
81
- _output_lines: Internal list for collecting output
82
- **extra: Additional CliRunner.invoke arguments
83
84
Returns:
85
Click Result object with execution details
86
"""
87
88
def declare_example(self, source):
89
"""
90
Execute Python code to define Click commands.
91
92
Parameters:
93
- source: Python source code string to execute
94
"""
95
96
def run_example(self, source):
97
"""
98
Execute example code and return formatted output lines.
99
100
Parameters:
101
- source: Python source code containing invoke() calls
102
103
Returns:
104
list: Lines of formatted input/output for documentation
105
"""
106
107
def close(self):
108
"""Clean up runner resources."""
109
```
110
111
### EofEchoingStdin
112
113
Custom stdin handler that displays EOF character visually in examples.
114
115
```python { .api }
116
class EofEchoingStdin(EchoingStdin):
117
"""
118
Enhanced EchoingStdin that shows EOF as ^D.
119
120
Extends Click's EchoingStdin to display a visible '^D' marker
121
when EOF character is encountered, improving documentation clarity.
122
"""
123
```
124
125
### Sphinx Directives
126
127
```python { .api }
128
class DeclareExampleDirective(Directive):
129
"""
130
Sphinx directive for declaring Click commands.
131
132
Processes Python code content and adds it to the document's
133
ExampleRunner namespace for later execution.
134
135
Attributes:
136
- has_content: True
137
- required_arguments: 0
138
- optional_arguments: 0
139
"""
140
141
class RunExampleDirective(Directive):
142
"""
143
Sphinx directive for executing Click commands.
144
145
Runs commands using the document's ExampleRunner and displays
146
the formatted input/output in the documentation.
147
148
Attributes:
149
- has_content: True
150
- required_arguments: 0
151
- optional_arguments: 0
152
"""
153
```
154
155
### Click Domain Class
156
157
```python { .api }
158
class ClickDomain(Domain):
159
"""
160
Sphinx domain for Click documentation.
161
162
Provides click:example and click:run directives for interactive
163
command-line documentation.
164
165
Attributes:
166
- name: "click"
167
- label: "Click"
168
- directives: {"example": DeclareExampleDirective, "run": RunExampleDirective}
169
"""
170
```
171
172
## Usage Examples
173
174
### Basic Command Documentation
175
176
Document a simple Click command with execution example:
177
178
```rst
179
.. click:example::
180
181
import click
182
183
@click.command()
184
@click.option('--count', default=1, help='Number of greetings')
185
@click.option('--name', prompt='Your name', help='Person to greet')
186
def hello(count, name):
187
"""Simple program that greets NAME for a total of COUNT times."""
188
for _ in range(count):
189
click.echo(f'Hello {name}!')
190
191
.. click:run::
192
193
invoke(hello, ['--count', '3', '--name', 'Alice'])
194
```
195
196
### Complex Command with Input
197
198
Document commands that require user input:
199
200
```rst
201
.. click:example::
202
203
@click.command()
204
@click.option('--interactive', is_flag=True, help='Interactive mode')
205
def configure(interactive):
206
if interactive:
207
name = click.prompt('Enter your name')
208
email = click.prompt('Enter your email')
209
click.echo(f'Configuration saved for {name} ({email})')
210
else:
211
click.echo('Non-interactive configuration')
212
213
.. click:run::
214
215
invoke(configure, ['--interactive'], input=['John Doe', 'john@example.com'])
216
```
217
218
### Environment Variables
219
220
Document commands with environment variable usage:
221
222
```rst
223
.. click:run::
224
225
invoke(hello, ['--name', 'Production'],
226
env={'DEBUG': 'false', 'ENV': 'production'})
227
```
228
229
### Custom Output Lines
230
231
Add explanatory text between command executions:
232
233
```rst
234
.. click:run::
235
236
invoke(hello, ['--help'])
237
println()
238
println("Now let's run the command:")
239
invoke(hello, ['--name', 'Documentation'])
240
```
241
242
### Multiple Commands
243
244
Document command groups and subcommands:
245
246
```rst
247
.. click:example::
248
249
@click.group()
250
def cli():
251
"""Main command group."""
252
pass
253
254
@cli.command()
255
def init():
256
click.echo('Initializing project...')
257
258
@cli.command()
259
@click.argument('name')
260
def create(name):
261
click.echo(f'Creating {name}...')
262
263
.. click:run::
264
265
invoke(cli, ['--help'])
266
invoke(cli, ['init'])
267
invoke(cli, ['create', 'myproject'])
268
```
269
270
## Helper Functions
271
272
```python { .api }
273
def get_example_runner(document):
274
"""
275
Get or create ExampleRunner for a document.
276
277
Parameters:
278
- document: Sphinx document object
279
280
Returns:
281
ExampleRunner: Runner instance associated with the document
282
"""
283
284
def delete_example_runner_state(app, doctree):
285
"""
286
Clean up ExampleRunner after document processing.
287
288
Parameters:
289
- app: Sphinx application instance
290
- doctree: Document tree being processed
291
"""
292
293
def patch_modules():
294
"""
295
Context manager for patching subprocess calls.
296
297
Redirects subprocess.call output to click.echo so it appears
298
in example output.
299
300
Returns:
301
ContextManager: Context manager for patched environment
302
"""
303
```