sphinx-autobuild
================

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


.. image:: https://img.shields.io/travis/GaretJax/sphinx-autobuild.svg
   :target: https://travis-ci.org/GaretJax/sphinx-autobuild
.. image:: https://img.shields.io/pypi/v/sphinx-autobuild.svg
   :target: https://pypi.python.org/pypi/sphinx-autobuild
.. image:: https://img.shields.io/coveralls/GaretJax/sphinx-autobuild/develop.svg
   :target: https://coveralls.io/r/GaretJax/sphinx-autobuild?branch=develop
.. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
   :target: http://sphinx-autobuild.readthedocs.org/en/latest/
.. image:: https://img.shields.io/pypi/l/sphinx-autobuild.svg
   :target: https://github.com/GaretJax/sphinx-autobuild/blob/develop/LICENSE


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`
* ``-B``/``--open-browser`` automatically open a web browser with the URL for
  this document
* ``--no-initial`` disable initial build
* ``-s``/``--delay`` delay in seconds before opening browser if
  ``--open-browser`` was selected (default 5)
* ``-z``/``--watch`` multiple allowed, option to specify additional directories
  to watch, for example: `some/extra/dir`
* ``--poll`` force polling, useful for Vagrant or VirtualBox which do not 
  trigger file updates in `shared folders`_

.. _shared folders: https://www.virtualbox.org/ticket/10660

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


Automatically starting a browser
--------------------------------

If you work on multiple Sphinx document repositories at one time (e.g., when
working with related documents that have cross-referencing intersphinx links),
managing multiple browser windows and manually selecting port numbers becomes
difficult and tedious. By selecting ``--port 0`` on the command line,
sphinx-autobuild will use `port-for`_ to generate a random high-numbered
port that is not currently being used.

To further simplify life, use the ``-B`` (``--open-browser``) option
to trigger livereload's capability of automatically opening a browser
window. Use ``-s`` (``--delay``) to change the number of seconds to
delay before starting the browser, and you may need to do something
like the following to ensure that all cached content is removed
before sphinx-autobuild starts watching files to fully render the
document properly::

    # Clean out any cached content before starting.
    make clean 2>/dev/null

    # Background a trigger for initial build of all files.
    (sleep 1 && touch source/*.rst) &

    sphinx-autobuild -q \
	    -p 0 \
	    --open-browser \
	    --delay 5 \
	    --ignore "*.swp" \
	    --ignore "*.pdf" \
	    --ignore "*.log" \
	    --ignore "*.out" \
	    --ignore "*.toc" \
	    --ignore "*.aux" \
	    --ignore "*.idx" \
	    --ignore "*.ind" \
	    --ignore "*.ilg" \
	    --ignore "*.tex" \
	    source \
	    build/html

.. _port-for: https://pypi.python.org/pypi/port-for/