0
# Command Line Interface
1
2
The sphinx-autobuild command-line interface provides comprehensive options for development server configuration, file watching, build customization, and browser integration. It extends standard Sphinx build arguments with autobuild-specific functionality.
3
4
## Capabilities
5
6
### Main Entry Point
7
8
The primary entry point that processes command-line arguments and starts the development server.
9
10
```python { .api }
11
def main(argv=()):
12
"""
13
Main entry point for sphinx-autobuild command.
14
15
Parameters:
16
- argv: list[str] | tuple[str, ...], optional - Command line arguments
17
(defaults to sys.argv[1:] if empty)
18
19
Raises:
20
- SystemExit: On argument parsing errors or Sphinx errors
21
- KeyboardInterrupt: Handled gracefully to stop server
22
"""
23
```
24
25
### Standard Arguments
26
27
Accepts all standard Sphinx build arguments plus autobuild-specific options:
28
29
```bash
30
# Required arguments (inherited from sphinx-build)
31
sphinx-autobuild <sourcedir> <outputdir>
32
33
# Standard Sphinx options
34
sphinx-autobuild docs _build/html -b html -E -a -v
35
```
36
37
### Server Configuration
38
39
Configure the development server host and port settings.
40
41
```bash { .api }
42
--port PORT # Port to serve documentation (default: 8000, 0 for free port)
43
--host HOST # Hostname to serve on (default: 127.0.0.1)
44
```
45
46
**Usage Examples:**
47
48
```bash
49
# Use default port 8000
50
sphinx-autobuild docs _build/html
51
52
# Use specific port
53
sphinx-autobuild docs _build/html --port 8080
54
55
# Find free port automatically
56
sphinx-autobuild docs _build/html --port 0
57
58
# Bind to all interfaces
59
sphinx-autobuild docs _build/html --host 0.0.0.0
60
61
# Custom host and port
62
sphinx-autobuild docs _build/html --host 192.168.1.100 --port 3000
63
```
64
65
### File Watching Options
66
67
Control which files are watched and which are ignored during development.
68
69
```bash { .api }
70
--ignore PATTERN # Glob pattern for files to ignore (repeatable)
71
--re-ignore REGEX # Regular expression for files to ignore (repeatable)
72
--watch DIR # Additional directories to watch (repeatable)
73
```
74
75
**Usage Examples:**
76
77
```bash
78
# Ignore temporary files
79
sphinx-autobuild docs _build/html --ignore "*.tmp" --ignore "*.swp"
80
81
# Ignore with regex patterns
82
sphinx-autobuild docs _build/html --re-ignore ".*\.backup$" --re-ignore ".*~$"
83
84
# Watch additional directories
85
sphinx-autobuild docs _build/html --watch ../shared --watch ../templates
86
87
# Combine ignore patterns
88
sphinx-autobuild docs _build/html --ignore "*.log" --re-ignore "__pycache__"
89
```
90
91
### Build Control Options
92
93
Configure the build process and initial behavior.
94
95
```bash { .api }
96
--no-initial # Skip the initial build on startup
97
--pre-build COMMAND # Command to run before each build (repeatable)
98
--post-build COMMAND # Command to run after each successful build (repeatable)
99
```
100
101
**Usage Examples:**
102
103
```bash
104
# Skip initial build
105
sphinx-autobuild docs _build/html --no-initial
106
107
# Run pre-build command
108
sphinx-autobuild docs _build/html --pre-build "echo Starting build"
109
110
# Multiple pre/post build commands
111
sphinx-autobuild docs _build/html \
112
--pre-build "python scripts/generate_api.py" \
113
--pre-build "echo Pre-processing complete" \
114
--post-build "python scripts/validate_links.py" \
115
--post-build "echo Build validation complete"
116
117
# Complex shell commands (properly quoted)
118
sphinx-autobuild docs _build/html \
119
--pre-build "find . -name '*.py' -exec python -m py_compile {} \;"
120
```
121
122
### Browser Integration
123
124
Automatically open browser and control timing.
125
126
```bash { .api }
127
--open-browser # Open browser after building documentation
128
--delay SECONDS # Delay before opening browser (default: 5.0)
129
```
130
131
**Usage Examples:**
132
133
```bash
134
# Open browser automatically
135
sphinx-autobuild docs _build/html --open-browser
136
137
# Open browser with custom delay
138
sphinx-autobuild docs _build/html --open-browser --delay 2.5
139
140
# Immediate browser opening
141
sphinx-autobuild docs _build/html --open-browser --delay 0
142
```
143
144
### Version Information
145
146
```bash { .api }
147
--version # Show sphinx-autobuild version and exit
148
```
149
150
### Complete Example
151
152
A comprehensive example showing multiple options:
153
154
```bash
155
sphinx-autobuild docs _build/html \
156
--port 8080 \
157
--host 0.0.0.0 \
158
--open-browser \
159
--delay 3 \
160
--ignore "*.tmp" \
161
--ignore "*.log" \
162
--re-ignore ".*\.backup$" \
163
--watch ../shared \
164
--watch ../templates \
165
--pre-build "python scripts/update_config.py" \
166
--post-build "python scripts/verify_output.py" \
167
-b html \
168
-E \
169
-v
170
```
171
172
## Environment Variables
173
174
### Debug Output
175
176
```bash { .api }
177
SPHINX_AUTOBUILD_DEBUG=1 # Enable debug output for file watching
178
```
179
180
When set to any non-empty value except "0", enables debug output showing file change notifications and ignore filter decisions.
181
182
**Usage:**
183
184
```bash
185
SPHINX_AUTOBUILD_DEBUG=1 sphinx-autobuild docs _build/html
186
```
187
188
## Error Handling
189
190
The CLI handles various error conditions gracefully:
191
192
- **Argument parsing errors**: Shows usage help and exits with error code
193
- **Sphinx build failures**: Continues serving but displays error message
194
- **Pre/post-build command failures**: Shows error and continues serving
195
- **Port binding failures**: Automatically finds alternative port if port 0 specified
196
- **Keyboard interrupt**: Clean shutdown with farewell message
197
- **File permission errors**: Graceful error reporting for inaccessible directories
198
199
## Exit Codes
200
201
- **0**: Normal termination or keyboard interrupt
202
- **1**: Argument parsing error or critical startup failure
203
- **2**: Sphinx argument validation failure