Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sphinx-doc/sphinx-autobuild

Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a hot-reload web server.
https://github.com/sphinx-doc/sphinx-autobuild

Last synced: 2 days ago
JSON representation

Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a hot-reload web server.

Awesome Lists containing this project

README 

        
================

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 `__.

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



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 `__

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 &



Relevant Sphinx Bugs

====================



Sphinx does not `detect changes in non-document, non-code files in incremental mode`__,

like theme files and static files.



At the time of writing, the only known workaround is

to instruct Sphinx to rebuild the relevant pages.

This can be done by disabling incremental mode (with ``-a``)

or passing relevant ``filenames`` in addition to source and output directory in the CLI.



__ https://github.com/sphinx-doc/sphinx-autobuild/issues/34



Acknowledgements

================



This project stands on the shoulders of giants,

without whom this project would not be possible.



Many thanks to everyone who has `contributed code`_ as well as

participated in `discussions on the issue tracker`_.

This project is better thanks to your contribution.



.. _contributed code: https://github.com/sphinx-doc/sphinx-autobuild/graphs/contributors

.. _discussions on the issue tracker: https://github.com/sphinx-doc/sphinx-autobuild/issues