Repository files navigation

Rebuild Sphinx documentation on changes, with hot reloading in the browser.

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

pip install sphinx-autobuild

To build a classical Sphinx documentation set, run:

sphinx-autobuild docs docs/_build/html

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

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

$sphinx-autobuild --helpusage: 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

FYI: Sphinx is planning tomove away from using Makefile.

To use sphinx-autobuild with the Makefile generated by Sphinx,add the following to the end of the Makefile:

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

make livehtml will now invoke sphinx-autobuild.

If you generated the Makefile with an older version of sphinx,this syntax might not work for you.Considerupdating to the newer structure.

sphinx-autobuild can open the homepage of the generated documentationin your default browser.Passing--open-browser will enable this behaviour.

sphinx-autobuild asks the operating system for a free port numberand use that for its server.Passing--port=0 will enable this behaviour.

When working on a Sphinx HTML theme,add the source directory of the theme as a watch directory.It is also recommended to disable Sphinx's incremental buildsby passing the-a option to sphinx-autobuild.

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

This results in slower builds, but it ensures thatall pages are built from the same state of the HTML theme.It also works around aknown issue in Sphinxwhich causes significant problems during theme development.

When working on multiple Sphinx documentation projects simultaneously,it is required to use different output directories for each project.It is also recommended to use--port=0 and--open-browserto avoid needing to manually manage ports and opening browser windows(which can get tedious quickly).

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

Sphinx does notdetect 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 isto instruct Sphinx to rebuild the relevant pages.This can be done by disabling incremental mode (with-a)or passing relevantfilenames in addition to source and output directory in the CLI.

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

Many thanks to everyone who hascontributed code as well asparticipated indiscussions on the issue tracker.This project is better thanks to your contribution.