sphinx-autobuild
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.
Installation
You can use pip
to install the package along with its requirements:
pip install sphinx-autobuild
Usage
The package installs a single executable script, named sphinx-autobuild
.
The script takes the same arguments as the sphinx-build
command installed
by Sphinx plus the following options:
-p
/--port
option to specify the port on which the documentation shall be served (default 8000)-H
/--host
option to specify the host on which the documentation shall be served (default 127.0.0.1)-i
/--ignore
multiple allowed, option to specify file ignore glob expression when watching changes, for example: *.tmp-z
/--watch
multiple allowed, option to specify additional directories to watch, for example: some/extra/dir
To build a classical Sphinx documentation set, issue the following command:
sphinx-autobuild docs docs/_build/html
And then visit the webpage served at http://127.0.0.1:8000. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded.
To stop the server simply press ^C
.
Makefile integration
To integrate the sphinx-autobuild command in the Makefile generated by Sphinx, add the following target:
livehtml: sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
Then run with:
make livehtml