sphinx-autobuild

sphinx-autobuild wraps sphinx-build in a file watcher and a lightweight Starlette web server, so documentation authors get an instant feedback loop instead of manually re-running builds and refreshing a browser tab. Point it at a source and output directory and it serves the generated HTML, watches the source tree with watchfiles, and triggers a rebuild the moment a file changes — injecting a small WebSocket script into every served page so open browser windows reload themselves automatically.

Beyond the basic watch-and-rebuild loop, it accepts the same arguments as sphinx-build directly, so existing Makefile-driven or CI-tuned build commands keep working unchanged. Additional watch directories, ignore patterns (glob or regex), pre-/post-build hooks, and automatic free-port selection make it flexible enough for multi-project setups, custom Sphinx themes under active development, and CI-adjacent local previews.

What You Get

• Automatic rebuilds on file change, powered by the watchfiles filesystem watcher
• A built-in Starlette/uvicorn web server that serves the freshly built HTML
• Live browser reload via an injected WebSocket script, no manual refresh needed
• Full compatibility with sphinx-build’s own CLI arguments and Makefile livehtml targets
• Configurable ignore patterns, extra watch directories, and pre-/post-build hook commands

Common Use Cases

• Local development of Sphinx-based documentation, especially large multi-page projects
• Developing or debugging a custom Sphinx HTML theme by watching the theme’s source directory alongside the docs
• Running many parallel documentation projects on auto-selected free ports for side-by-side previews
• Wiring pre-build/post-build hooks into a local workflow, e.g. desktop notifications on build start/finish

Under The Hood

Architecture sphinx-autobuild is a small, cleanly layered ASGI application: __main__.py parses arguments (reusing Sphinx’s own build-argument parser for compatibility), then wires together a Builder (build.py), a RebuildServer (server.py), and an IgnoreFilter (filter.py) into a Starlette app served by uvicorn. The RebuildServer runs as an asyncio background task under Starlette’s lifespan, watching the source tree with watchfiles.awatch and dispatching each detected change to the Builder inside a ProcessPoolExecutor so a slow Sphinx build never blocks the event loop or the WebSocket reload channel. A JavascriptInjectorMiddleware rewrites outgoing HTML responses to append a small reload script, decoupling the live-reload mechanism from the static file server that ships the built docs. Changing the underlying build tool would mean rewriting Builder, but the watch/serve/inject layers are otherwise independent and swappable.

Tech Stack Written in modern, type-hinted Python (3.11+, with from __future__ import annotations throughout) with a minimal, purpose-built dependency set: Starlette and uvicorn provide the ASGI server and static file mount, watchfiles handles cross-platform filesystem watching, websockets backs the live-reload channel, and colorama normalizes console output on Windows. It shells out to python -m sphinx for the actual documentation build rather than reimplementing any Sphinx internals, keeping it forward-compatible with new Sphinx releases. Packaging uses flit-core with a dynamic version, distributed as a single console-script entry point.

Code Quality The test suite (test_ignore.py, test_application.py) is comparatively light for the codebase’s size, covering the ignore-filter logic and basic application wiring but not the build or WebSocket-reload paths directly. CI runs this suite across four Python versions via nox, alongside a separate pre-commit job that runs Ruff (lint and format) and validate-pyproject on every push. There is no dedicated static type-checking job, though the code is type-annotated throughout. Overall a lint-and-CI-enforced but lightly-tested project.

API Design The primary interface is the sphinx-autobuild CLI, deliberately designed as a drop-in superset of sphinx-build — it accepts the same source/output directory positional arguments and forwards unrecognized flags straight to Sphinx, so existing Makefile livehtml targets and CI invocations need no rewriting. Autobuild-specific behavior (—watch, —ignore, —re-ignore, —pre-build, —post-build, —port=0 for auto-selection) is added as a clearly separated argument group rather than mixed into Sphinx’s own options, keeping the tool’s surface area predictable for anyone already familiar with sphinx-build.