0
# Sphinx Autobuild
1

2
An automated development server for Sphinx documentation that watches for file changes and automatically rebuilds documentation with hot reloading in the browser. It provides comprehensive command-line interface with options for custom ports, host configuration, file watching patterns, pre/post-build commands, and browser automation.
3

4
## Package Information
5

6
- **Package Name**: sphinx-autobuild
7
- **Language**: Python
8
- **Installation**: `pip install sphinx-autobuild`
9
- **Requires**: Python ≥3.11
10

11
## Core Imports
12

13
```python
14
import sphinx_autobuild
15
```
16

17
For programmatic use:
18

19
```python
20
from sphinx_autobuild import __version__
21
from sphinx_autobuild.__main__ import main
22
from sphinx_autobuild.build import Builder
23
from sphinx_autobuild.server import RebuildServer
24
from sphinx_autobuild.filter import IgnoreFilter
25
from sphinx_autobuild.middleware import JavascriptInjectorMiddleware, web_socket_script
26
from sphinx_autobuild.utils import find_free_port, open_browser, show_message, show_command
27
```
28

29
## Basic Usage
30

31
### Command Line Usage
32

33
```bash
34
# Basic usage - watch source directory and serve on localhost:8000
35
sphinx-autobuild docs _build/html
36

37
# Custom port and host
38
sphinx-autobuild docs _build/html --port 8080 --host 0.0.0.0
39

40
# Open browser automatically
41
sphinx-autobuild docs _build/html --open-browser
42

43
# Ignore specific files and patterns
44
sphinx-autobuild docs _build/html --ignore "*.tmp" --re-ignore ".*\.swp$"
45

46
# Watch additional directories
47
sphinx-autobuild docs _build/html --watch ../source --watch ../templates
48

49
# Run pre/post build commands
50
sphinx-autobuild docs _build/html --pre-build "echo Starting" --post-build "echo Done"
51
```
52

53
### Programmatic Usage
54

55
```python
56
from sphinx_autobuild.__main__ import main
57

58
# Run with custom arguments
59
main(['docs', '_build/html', '--port', '8080'])
60

61
# Or use sys.argv style
62
import sys
63
sys.argv = ['sphinx-autobuild', 'docs', '_build/html', '--open-browser']
64
main()
65
```
66

67
## Architecture
68

69
Sphinx-autobuild uses an event-driven architecture with several key components:
70

71
- **Builder**: Manages Sphinx build process and pre/post-build commands
72
- **RebuildServer**: Handles file watching via WebSocket connections with browser clients  
73
- **IgnoreFilter**: Filters file changes using glob patterns and regular expressions
74
- **JavascriptInjectorMiddleware**: Injects WebSocket client code into served HTML pages
75
- **Starlette ASGI App**: Serves static files and handles WebSocket connections for hot reloading
76

77
The system uses uvicorn as the ASGI server and watchfiles for efficient file system monitoring. When changes are detected, it rebuilds documentation and notifies connected browser clients to reload.
78

79
## Capabilities
80

81
### Command Line Interface
82

83
Primary way to use sphinx-autobuild with comprehensive options for development server configuration, file watching, build customization, and browser integration.
84

85
```python { .api }
86
def main(argv=()):
87
    """Main entry point for sphinx-autobuild command.
88
    
89
    Parameters:
90
    - argv: Command line arguments (optional, defaults to sys.argv[1:])
91
    """
92
```
93

94
[Command Line Interface](./cli.md)
95

96
### Build Management
97

98
Controls the Sphinx documentation build process with support for pre/post-build commands and error handling.
99

100
```python { .api }
101
class Builder:
102
    def __init__(self, sphinx_args, *, url_host, pre_build_commands, post_build_commands):
103
        """Initialize builder with Sphinx arguments and command hooks."""
104
    
105
    def __call__(self, *, changed_paths):
106
        """Execute build process when files change."""
107
```
108

109
[Build Management](./build.md)
110

111
### File Watching & Server
112

113
Watches file system for changes and serves documentation with hot reloading via WebSocket connections.
114

115
```python { .api }
116
class RebuildServer:
117
    def __init__(self, paths, ignore_filter, change_callback):
118
        """Initialize file watching server."""
119
    
120
    async def __call__(self, scope, receive, send):
121
        """ASGI application for WebSocket connections."""
122
```
123

124
[File Watching & Server](./server.md)
125

126
### File Filtering
127

128
Provides flexible file filtering using glob patterns and regular expressions to ignore specific files and directories during watching.
129

130
```python { .api }
131
class IgnoreFilter:
132
    def __init__(self, regular, regex_based):
133
        """Initialize filter with glob patterns and regex patterns."""
134
    
135
    def __call__(self, filename):
136
        """Check if file should be ignored."""
137
```
138

139
[File Filtering](./filtering.md)
140

141
### HTTP Middleware
142

143
ASGI middleware for injecting WebSocket client code into HTML responses to enable hot reloading functionality.
144

145
```python { .api }
146
class JavascriptInjectorMiddleware:
147
    def __init__(self, app, ws_url):
148
        """Initialize middleware with ASGI app and WebSocket URL."""
149
    
150
    async def __call__(self, scope, receive, send):
151
        """ASGI middleware callable for HTTP requests."""
152

153
def web_socket_script(ws_url):
154
    """Generate WebSocket JavaScript code for browser auto-reload."""
155
```
156

157
[HTTP Middleware](./middleware.md)
158

159
### Utility Functions
160

161
Helper functions for port management, browser automation, and formatted console output.
162

163
```python { .api }
164
def find_free_port():
165
    """Find and return a free port number."""
166

167
def open_browser(url_host, delay):
168
    """Open browser to specified URL after delay."""
169

170
def show_message(context):
171
    """Show message with colored formatting."""
172

173
def show_command(command):
174
    """Show command with colored formatting."""
175
```
176

177
[Utility Functions](./utils.md)
178

179
## Types
180

181
```python { .api }
182
# Type aliases used throughout the API
183
from collections.abc import Callable, Sequence
184
from pathlib import Path
185
from typing import TYPE_CHECKING
186

187
if TYPE_CHECKING:
188
    import os
189
    from starlette.types import ASGIApp, Message, Receive, Scope, Send
190
    from starlette.websockets import WebSocket
191
    
192
# Common type patterns
193
PathLike = os.PathLike[str]
194
ChangeCallback = Callable[[Sequence[Path]], None]
195
CommandList = list[str] | tuple[str, ...]
196
```