Repolode
Submit
sphinx-doc

sphinx-doc/sphinx-autobuild

A command-line tool that watches a Sphinx documentation directory, rebuilds the docs on changes, and reloads the browser via a local server.

View on GitHub
Stars
611
Forks
100
Open issues
34
Last commit
16 days ago

What is it?

sphinx-autobuild watches a Sphinx source directory and runs sphinx-build whenever a file changes. It serves the generated HTML over a local web server at http://127.0.0.1:8000 by default, and open browser windows reload automatically after each rebuild, so authors can see edits without manually rebuilding or refreshing.

It accepts the same arguments as sphinx-build and adds options for host and port (port 0 picks a free port), ignore patterns by glob or regex, extra directories to watch, pre-build and post-build commands, and opening the browser once the server is ready. A Makefile target can wrap it to provide a 'livehtml' command.

The tool is useful when writing documentation or developing a Sphinx HTML theme. For theme work, it can watch the theme directory too, and disabling incremental builds with -a ensures every page is rebuilt from the same theme state.

Key features

  • 01Rebuilds Sphinx docs automatically when files in the source directory change.
  • 02Reloads open browser windows after each build.
  • 03Accepts all sphinx-build arguments and adds server and watch options.
  • 04Supports glob and regex ignore patterns for watched files.
  • 05Runs custom commands before and after each build.
  • 06Can pick a free port automatically and open the browser on startup.

Use cases

  • Writing and previewing project documentation with instant feedback.
  • Developing a custom Sphinx HTML theme while watching theme files.
  • Running several documentation projects at once with separate ports and output directories.
  • Sending build start and finish notifications through pre- and post-build hooks.

Quick start

  1. 1

    Install sphinx-autobuild from PyPI with pip

    pip install sphinx-autobuild
  2. 2

    Start the server and watch the docs directory for changes

    sphinx-autobuild docs docs/_build/html

Things to know

  • Requires a Sphinx documentation project to be useful.

In collections

Static site generators & documentation tools

Topics

#sphinx#documentation#live-reload#hot-reload#python#docs-tooling

FAQ

What is sphinx-autobuild?
A command-line tool that watches a Sphinx documentation directory, rebuilds the docs on changes, and reloads the browser via a local server. sphinx-autobuild watches a Sphinx source directory and runs sphinx-build whenever a file changes. It serves the generated HTML over a local web server at http://127.0.0.1:8000 by default, and open browser windows reload automatically after each rebuild, so authors can see edits without manually rebuilding or refreshing.
Is sphinx-autobuild free to use? What license does it have?
sphinx-autobuild is open source under the MIT license. Check the license terms before using it in commercial products.
Is sphinx-autobuild still maintained?
Actively maintained. The last commit to sphinx-autobuild was on Oct 23, 2026.
What can I use sphinx-autobuild for?
Writing and previewing project documentation with instant feedback. Developing a custom Sphinx HTML theme while watching theme files. Running several documentation projects at once with separate ports and output directories. Sending build start and finish notifications through pre- and post-build hooks.
How do I install sphinx-autobuild?
Install sphinx-autobuild from PyPI with pip: pip install sphinx-autobuild Start the server and watch the docs directory for changes: sphinx-autobuild docs docs/_build/html
Where can I get sphinx-autobuild?
The source code and installation instructions are on GitHub: https://github.com/sphinx-doc/sphinx-autobuild

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects