reStructuredText in PyCharm, Firefox, and Anger
I spend a lot of time writing Python package documentation in reST. Nevertheless, I find reST's markup permanently unlearnable, so I format docs by trial and error: I type a few backticks and colons and angle-brackets and random crap,
sphinx-build the docs as HTML, and see if they look okay.
Here's some tools to support this expert workflow.
PyCharm: My favorite Python IDE has basic syntax-highlighting and auto-completion for reST. It's not much, but it far exceeds the amount of reStructuredText syntax that can fit in my tiny brain. It really shines when I'm embedding Python code examples in my docs: PyCharm gives me full IDE support, including automatically adding imports, auto-completing method names and parameters, and nearly all the help I get when editing normal Python files.
There's a file-watcher plugin for PyCharm that seems like a nice way to rebuild docs when the source files change, but it's not yet compatible with the latest version of PyCharm. So instead:
Watchdog: I install the watchdog Python package, which watches files and directories for changes. Watchdog gives me a command-line tool called
watchmedo. (I find this fact unlearnable, too; why isn't the tool called
watchdog the same as the package?) I tell it to watch my package's files for changes and rebuild the docs whenever I save a file:
watchmedo shell-command --command="sphinx-build doc build" .
Now that I can regenerate HTML automatically, I need a way to reload the browser window automatically:
auto-reload is a Firefox extension that detects any tab with a
This little suite of tools deals well with invoking Sphinx and reloading my web page, so I can focus on the task at hand: trying to write reStructuredText, which is a loathsome afterbirth expelled from the same womb as XML and TeX.