Metadata-Version: 1.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
Description: 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.
        
Platform: UNKNOWN
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
