TextMate is great for general editing of most text formats. By default,
reStructuredText is not one
of them. This document describes how to fix TextMate so that it is a better
fit for the tools I work with. We want reStructuredText rendered previews
and HTML export functions in TextMate.

Update Monday July 6, 2009: TextMate’s bundle repository has moved. This
article has been updated to reflect this change.

Install reStructuredText TextMate Bundle

TextMate has a bundle repository at
http://svn.textmate.org/trunk/Bundles with a reStructuredText
bundle already built. We need to download that to a place where TextMate will
actually find the bundle and load it. Typically, thats
~/Library/Application Support/TextMate/Bundles.

Make reStructuredText Bundle use virtualenv

Now that we have the bundle, we need to let it know that it needs to be
called from inside our virtualenv. The Preview command uses rst2html.py
to generate the preview, and luckily provides a way to customize the path
to rst2html.py. All we need to do is define TM_RST2HTML variable
with the correct path in our .bash_profile and TextMate will find the
right one.

Bask in the glory

We’re done. Now we can preview or export reStructuredText easily. Open a
reStructuredText file and go wild. It’s incredibly convenient to preview
documents as you go, and saving them to HTML makes it simple to blog from
TextMate.

(TextMate)stewart:~ xdissent$ mate ~/Documents/TextMate\ Fixes.rst

Colour My World

If you’re like me, you tend to include source code or console sessions in
your articles. Pygments is a Python package that
can add syntax highlighting to these snippets, which comes in handy for
previewing in TextMate. Installation is slightly more advanced, but well
worth setting up.

Install Mercurial

We want to hack on our Pygments package, so we’re going to want to install
it in editable mode. Plus, the latest stable release doesn’t have the
BashSessionLexer that I use quite a bit. Pygments uses Mercurial for source control, but I don’t have
a system-wide copy of hg, so I needed to grab one real fast.

Install the reStructuredText sourcecode directive

Activating syntax highlighting in a document requires the sourcecode
directive which highlights the following block of code. We can switch out
different Pygments lexers using an option after the directive:

The sourcecode directive isn’t installed automatically, so we’ll need to
add it ourselves. Directives are simply python functions that must be
registered with docutils before any parsing is done. That means we can’t use
rst2html.py with highlighting yet because the directive won’t be loaded.
Pygments does come with the directive already in its source tree, but we’re
going to have to let virtualenv know where it is, and then modify rst2html.py
to register the directive before it begins parsing.

Colorize the Preview command

What good is all this work if we can’t see the damn colors? As it stands now,
pygments is marking up our code to be colorized, but the CSS to actually make
the colors show up isn’t being loaded into our preview window. We have to
enhance the Preview command in the reStructuredText bundle to include Pygments
stylesheets. You can control which Pygments theme will be used by defining
a TM_PYGMENTIZE_STYLE environment variable. I’ve created a patch that we
can apply to update our bundle.

Tell TextMate how to use pygmentize

The patch for the Preview command requires an environment variable called
TM_PYGMENTIZE that contains the path to the pygmentize script. We
need to add that to our .bash_profile along with any custom style we want
to use for highlighting.

Inform TextMate of the updated Preview command

Patch Pygments for virtualenv

Everything should be working perfectly now in full color, but I went one step
further in my setup to tweak the BashSessionLexer in Pygments. Because I
use virtualenv all the time, my bash prompt usually has a virtual env name
at the beginning, surrounded by parentheses. If I were to use the console
option for sourcecode with a virtualenv active in the session, the lexer
wouldn’t recognize my prompt and it wouldn’t get highlighted. I put together
a quick patch for Pygments that correctly highlights virtualenvwrapper style
prompts.