Metadata-Version: 2.1
Name: sphinx-autobuild
Version: 0.7.1
Summary: Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.
Home-page: https://github.com/GaretJax/sphinx-autobuild
Author: Jonathan Stoppani
Author-email: jonathan@stoppani.name
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: watchdog>=0.7.1
Requires-Dist: argh>=0.24.1
Requires-Dist: pathtools>=0.1.2
Requires-Dist: PyYAML>=3.10
Requires-Dist: tornado>=3.2
Requires-Dist: port-for==0.4
Requires-Dist: livereload>=2.3.0

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/


Changelog
=========

0.7.1 - 2017/07/05
------------------

* Remove spurious virtualenv directory from published packages.


0.7.0 - 2017/07/05
------------------

* Add support for python 3.5, 3.6 and deprecate official python 2.6 support.
* Add ``__main__`` module for python 3.
* Add a ``--version`` argument.


0.6.0 – 2016/02/14
------------------

* Support ``-p 0``, ``--port=0`` to automatically chose an available port.
* Added ``-B``, ``--open-browser`` to automatically open the documentation upon
  build.
* Added Kate swap files to the list of files ignored by default
* Automatically build docs on startup (can be disabled with ``--no-initial``).
* Added ``--poll`` to force polling the FS for changes (useful for
  networked/virtualized mountpoints).
* Compatibility with livereload >= 2.4.1.


0.5.2 – 2015/04/10
------------------

* Added ``-r``, ``--re-ignore`` command line argumet to exclude paths using
  regexes.


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.
