sphinx-autobuild 0.5.1

Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

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

Unreleased

0.5.0 – 2015/01/28

• Added -z, –watch command line argument to watch arbitrary folders

0.4.0 – 2014/12/23

• Added -i, –ignore command line argument to ignore files by the glob expression.

• Added basic tests for the entry point script.

• PEP 257 improvements.

• Automated tests on travis integration and coverage reporting.

• Compatibility with livereload >= 2.3.0.

• Compatibility with Python 2.6 and 2.7.

• Provisional compatibility with Python 3.3 and 3.4.

0.3.0 – 2014/08/21

0.2.3 – 2013/12/25

• Ignore the paths indicated by the -w and -d arguments when watching for changes to the documentation.

0.2.1 – 2013/12/25

• Catch subprocess PTY reading errors.

0.2.0 – 2013/12/25

• Explicitly parse sphinx-build arguments for better compatibility.

0.1.0 – 2013/12/25

• Initial release.