flymake with Sphinx

Working on my PyCon tutorial (next week!), I’ve been spending a lot of time in Emacs editing reStructured Text documents. I use Sphinx and Hieroglyph to generate the HTML, the slides, and the PDF from a single source, which make it easy for me to keep everything in sync. flymake is an Emacs mode that’s designed to do syntax or spell checking as you work. The name reveals its roots: in its simplest form, it just runs make for your project.

I was tired of flipping over to the shell to re-build the Sphinx project, so I decided to enable flymake for .rst files and see what happened. The flymake-allowed-file-name-masks variable has a list of regular expressions to flymake commands, so I added the following element to the list:

("\\.rst\\'" flymake-simple-make-init)

That was enough to get flymake to invoke the Makefile, and then I just needed to add the target it looks for: check-syntax. I added the following target to my Sphinx project Makefile:

check-syntax:
        $(SPHINXBUILD) -n -N -q -b html $(ALLSPHINXOPTS) $(BUILDDIR)/
        $(SPHINXBUILD) -n -N -q -b slides $(ALLSPHINXOPTS) $(BUILDDIR)/slides

In my case I’m building both HTML and Slides from the Sphinx project, and I wanted both to be updated when I changed a file in Emacs. That did it.

Now all I wanted was automagic execution of make, but to my pleasant surprise, Sphinx’s warning and error output is compatible with flymake by default. Suddenly Emacs highlighted missing targets and directives with missing arguments in red. With flymake-cursor enabled, moving my cursor over one of those red lines showed me the Sphinx error below the mode-line.

There you have it: Sphinx just works with Emacs and flymake, you just need to turn it on.