sphinx-autobuild 2024.9.19

Installation

sphinx-autobuild is available on PyPI. It can be installed using pip:

pip install sphinx-autobuild

Usage

To build a classical Sphinx documentation set, run:

sphinx-autobuild docs docs/_build/html

This will start a server at http://127.0.0.1:8000 and start watching for changes in the docs/ directory. When a change is detected in docs/, the documentation is rebuilt and any open browser windows are reloaded automatically. KeyboardInterrupt (ctrl + c) will stop the server.

Command line options

sphinx-autobuild accepts the same arguments as sphinx-build (these get passed to sphinx-build on each build). It also has a few additional options, which can seen by running sphinx-autobuild --help:

$ sphinx-autobuild --help
usage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]

...

autobuild options:
  --port PORT           port to serve documentation on. 0 means find and use a free port
  --host HOST           hostname to serve documentation on
  --re-ignore RE_IGNORE
                        regular expression for files to ignore, when watching for changes
  --ignore IGNORE       glob expression for files to ignore, when watching for changes
  --no-initial          skip the initial build
  --open-browser        open the browser after building documentation
  --delay DELAY         how long to wait before opening the browser
  --watch DIR           additional directories to watch
  --pre-build COMMAND   additional command(s) to run prior to building the documentation

livehtml:
   sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Workflow suggestions

sphinx-autobuild -a docs docs/_build/html --watch path/to/theme

sphinx-autobuild --port=0 --open-browser pikachu/docs pikachu/docs/_build/html &
sphinx-autobuild --port=0 --open-browser magikarp/docs magickarp/docs/_build/html &

Relevant Sphinx Bugs

Sphinx does not detect changes in non-document, non-code files in incremental mode, like theme files and static files.

At the time of writing, the only known workaround is to instruct Sphinx to rebuild the relevant pages. This can be done by disabling incremental mode (with -a) or passing relevant filenames in addition to source and output directory in the CLI.

Acknowledgements

This project stands on the shoulders of giants, without whom this project would not be possible.

Many thanks to everyone who has contributed code as well as participated in discussions on the issue tracker. This project is better thanks to your contribution.