Last Updated: February 25, 2016
· kevgathuku

Rebuild sphinx docs when a source file is modified

When writing documentation using Sphinx, it gets pretty annoying to have to manually run make html everytime you make a change to a source file to see the result in the generated HTML file.

Let's use a simple Python program called rerun to fix this.

First of all, let's install the program from pypi

pip install rerun

(This works with both Python 2 and Python 3)

Now let's cd into the docs directory which we are assuming contains the source files

cd docs

And we finally run the rerun command in this directory.

rerun -v -i=_build "make html"

The -v flag tells the command to run in verbose mode

The -i flag instructs the command to ignore the _build directory.

(This is the folder where the generated files are placed, so we are not interested in changes in that directory.)

Finally the command in quotes is the actual command that we want to run when any file in the current directory changes. In this case it is make html

And that's it.

Now, everytime a source file in the docs directory is edited, the make html command will be run automatically