Yann Malet came up with a nifty trick to deal with the write/compile/refresh cycle that usually accompanies working with marked up content such as one typically uses for technical documentation. For example, in a terminal:

$ watch sphinx-build sourcedir builddir

This would run the Sphinx documentation builder every 2 seconds (see man watch to override). If you use the Epiphany browser it will refresh automatically when it detects the source page has changed. Slick! It just makes the writing process feel more interactive and the little adrenaline rush from seeing the live document update as you work can be addicting.

A Small Step Further

That said, relying directly on polling for just about anything in software development is going to be "so last decade" pretty soon. Chris Heisel pointed us to his pywatch project and it offers a way to create a more event-driven setup. pywatch runs a command whenever files you specify have changed. Now we have an easy way to have the documentation builder run only when there is updated content.

Install:

#Pick your poison:
$ easy_install pywatch
#Or
$ pip install pywatch
#Or
$ pip install -e git+http://github.com/cmheisel/pywatch.git#egg=pywatch

In a fresh terminal:

$ pywatch "sphinx-build sourcedir builddir" in_progress.rst

You can extend this concept to give yourself simple automation for your different parts of your development workflow. Running tests is a natural candidate for this but you could also use it to do things like compressing your static files after you edit them, or running pylint and PEP8 checkers on files you're editing. Then every time you finish writing a class or function you can instantly check the code quality against those standards.