I've found a useful set of tools for writing RST, when I must. I'll show you how to configure LiveReload and Chrome to make the experience of writing RST's tortured syntax somewhat bearable.

(This article is an improvement over the method I wrote about last year.)


I bought LiveReload from the Mac App Store for $10, and opened it. Under "Monitored Folders" I added my project's home directory: I was updating Motor's documentation so I added the "motor/doc" directory.


Next to "Monitoring 44 file extensions" I hit "Options" and added "rst" as a 45th.

LiveReload file extension options

Then I checked "Run custom command after processing changes" and hit "Options". In the popup dialog I added the command for building Motor's documentation. It's a typical Sphinx project, so the build command is:

/Users/emptysquare/.virtualenvs/motor/bin/sphinx-build \
  -b html -d _build/doctrees . _build/html

Note that I specified the full path to the virtualenv'ed sphinx script.

That's all there is to configuring LiveReload. Hit the green box on the lower right of its main window to see the build command's output. Now whenever you change an RST file you should see some Sphinx output scroll by:

LiveReload Sphinx output


Next, follow LiveReload's instructions for installing the Chrome extension. Pay attention to LiveReload's tip: "If you want to use it with local files, be sure to enable 'Allow access to file URLs' checkbox in Tools > Extensions > LiveReload after installation."

Now open one of the HTML files Sphinx made, and click the LiveReload icon on your browser to enable it. The difference between "enabled" and "disabled" is damn subtle. This is disabled:


This is enabled:


The icon plays it close to the chest, but if you hover your mouse over it, it'll admit whether it's enabled or not.

Back at the LiveReload application, you'll now see "1 browser connected."

Try it out! Now you can make changes to your RST and see it live in your browser. I don't think I'll ever learn to type RST's syntax reliably, but at least now, I can see at once whether I've typed it right or not.