Description

================ sphinx-autobuild ================ .. image:: https://img.shields.io/pypi/v/sphinx-autobuild.svg :target: https://pypi.org/project/sphinx-autobuild/ :alt: Package on PyPI .. image:: https://img.shields.io/badge/License-MIT-blue.svg :target: https://opensource.org/licenses/MIT :alt: MIT Rebuild Sphinx documentation on changes, with hot reloading in the browser. .. image:: ./docs/_static/demo.png :align: center :alt: preview screenshot Installation ============ sphinx-autobuild is available on `PyPI <https://pypi.org/project/sphinx-autobuild/>`__. It can be installed using pip: .. code-block:: bash pip install sphinx-autobuild Usage ===== To build a classical Sphinx documentation set, run: .. code-block:: bash sphinx-autobuild docs docs/_build/html This will start a server at http://127.0.0.1:8000 and start watching for changes in the ``docs/`` directory. When a change is detected in ``docs/``, the documentation is rebuilt and any open browser windows are reloaded automatically. ``KeyboardInterrupt`` (``ctrl`` + ``c``) will stop the server. Command line options ==================== sphinx-autobuild accepts the same arguments as ``sphinx-build`` (these get passed to sphinx-build on each build). It also has a few additional options, which can seen by running ``sphinx-autobuild --help``: .. code-block:: console $ sphinx-autobuild --help usage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...] ... autobuild options: --port PORT port to serve documentation on. 0 means find and use a free port --host HOST hostname to serve documentation on --re-ignore RE_IGNORE regular expression for files to ignore, when watching for changes --ignore IGNORE glob expression for files to ignore, when watching for changes --no-initial skip the initial build --open-browser open the browser after building documentation --delay DELAY how long to wait before opening the browser --watch DIR additional directories to watch --pre-build COMMAND additional command(s) to run prior to building the documentation --post-build COMMAND additional command(s) to run after building the documentation Using with Makefile ------------------- FYI: Sphinx is planning to `move away from`_ using `Makefile`. To use sphinx-autobuild with the Makefile generated by Sphinx, add the following to the end of the Makefile: .. code-block:: make livehtml: sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) ``make livehtml`` will now invoke sphinx-autobuild. If you generated the `Makefile` with an older version of sphinx, this syntax might not work for you. Consider `updating to the newer structure`_. .. _move away from: https://github.com/sphinx-doc/sphinx/issues/5618#issuecomment-502415633 .. _updating to the newer structure: https://github.com/sphinx-doc/sphinx/blob/v3.0.0/sphinx/templates/quickstart/Makefile.new_t Automatically opening the browser --------------------------------- sphinx-autobuild can open the homepage of the generated documentation in your default browser. Passing ``--open-browser`` will enable this behaviour. Automatically selecting a port ------------------------------ sphinx-autobuild asks the operating system for a free port number and use that for its server. Passing ``--port=0`` will enable this behaviour. Workflow suggestions ==================== Working on a Sphinx HTML theme ------------------------------ When working on a Sphinx HTML theme, add the source directory of the theme as a watch directory. It is also recommended to disable Sphinx's incremental builds by passing the ``-a`` option to sphinx-autobuild. .. code-block:: bash sphinx-autobuild -a docs docs/_build/html --watch path/to/theme This results in slower builds, but it ensures that all pages are built from the same state of the HTML theme. It also works around a `known issue in Sphinx <relevant sphinx bugs_>`__ which causes significant problems during theme development. Working on multiple projects ---------------------------- When working on multiple Sphinx documentation projects simultaneously, it is required to use different output directories for each project. It is also recommended to use ``--port=0`` and ``--open-browser`` to avoid needing to manually manage ports and opening browser windows (which can get tedious quickly). .. code-block:: bash sphinx-autobuild --port=0 --open-browser pikachu/docs pikachu/docs/_build/html & sphinx-autobuild --port=0 --open-browser magikarp/docs magickarp/docs/_build/html & Notifications for build cycles ------------------------------ As an example of using the ``--pre-build`` and ``--post-build`` arguments, the command below uses `notify-send` to send a notification when a build starts and finishes. .. code-block:: bash sphinx-autobuild docs d