Automatically build Sphinx documentation when a source file changes

Question

I'm using Sphinx to document one of my projects, and I like to preview my changes in my browser. I want to be able to save some changes to an .rst file, and be able to immediately refresh my browser and see the changes.

Essentially I want to automatically execute a make html whenever one of the .rst files is changed.

Answer 1

You can use sphinx-autobuild.

It is easy to use, for example:

sphinx-autobuild docs docs/_build/html

or, if you have a separate build dir,

sphinx-autobuild source build/html

It will also automatically initiate a page refresh in the browser.