Previewing restructuredtext documents

These are instructions to install restview, that is a software to quickly preview the restructuredText documents created with a text editor in a browser. My Linux distribution is Archlinux, so you may have to adapt some commands for yours.

Install docutils (it is the package that process the restructured text to convert it to html):

pacman -S python2-docutils

Install pygments:

pacman -S python2-pygments

Install the restview previewer:

yaourt -S restview

Now it is necessary to make docutils aware of a new directive (like a new command) that we will use to markup pieces of source code in the restructured text file.

Download the restructuredtext directive rst-directive that comes with pygments and save it as ~/bin/rst_directive.py. You can edit it to modify the directive, specially the command directive name used to activate the pygments processor. I leave it as sourcecode as it comes by default.

Create a copy of restview command to a user directory that is included in the PATH before the /usr/bin/:

cp /usr/bin/restview ~/bin

Edit the copied file so that it imports the directive before processing the rest file. In my case it looks like this:

#!/usr/bin/python2
# EASY-INSTALL-ENTRY-SCRIPT: 'restview==1.2.2','console_scripts','restview'
__requires__ = 'restview==1.2.2'
import sys
from pkg_resources import load_entry_point

# Edited for REST directive:
sys.path.append('/home/marco/bin')
import rst_directive

if __name__ == '__main__':
  sys.exit(
      load_entry_point('restview==1.2.2', 'console_scripts', 'restview')()
  )

Now, when I run command restview from command line, the ~/bin/restview gets executed instead of /usr/bin/restview and the directive is imported so it is available.

I can then insert code in this way:

.. sourcecode:: python

    print "Hello world"

I can edit it in vim for example and if I run the command restview <myfile.rst> a browser opens and connects to a local port to preview the converted file. Every time I save it and press reload in the browser the local server restview converts it again to HTML.

References:

• Using Pygments in ReST documents
• Restview at pypi