Rebuild Sphinx Docs Automatically + Live Reload

I’ve been working on a bunch of Sphinx documentation recently. Maybe you don’t write a lot of documentation, but you should be!

Currently, I’m working on a REVSYS client project. It’s just at the design and architecture phase right now, but we know the resulting systems are going to be built with Python so of course, we’re going to be using Sphinx for the documentation.

One thing that has always bugged me about working with Sphinx is you spend a lot of time writing in reStructured text in an editor and often find small syntax bugs only when you go to build the docs. Today I realized I could probably work up a gulp setup that would watch my source reST, rebuild the docs, and probably live reload a browser tab with the docs.

Luckily before I wasted too much time, I did a quick Google search and found sphinx-autobuild which does this all for me. This is all you need to do to get going.

pip install sphinx-autobuild
sphinx-autobuild [path/to/source/docs/] [path/to/build/html]

And point your browser to http://localhost:8000. Using a fairly standard setup of a docs directory with separate ‘source’ and ‘build’ directories my exact command was this from the root of the repository checkout.

sphinx-autobuild docs/source/ docs/build/html/

I’ve only been using it for a few minutes and it’s already proven itself to be useful. Hope this helps you to not only write more documentation but to enjoy it more at the same time.

Happy Hacking!

Frank Wiles

Founder of REVSYS and former President of the Django Software Foundation . Expert in building, scaling and maintaining complex web applications. Want to reach out? Contact me here or use the social links below.