Previewing restructuredtext documents2013-03-06 Filed under linux, Tags markup web python
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
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.