How to render reStructuredText documents with latest docutils on Ubuntu 12.04 LTS


python pip docutils restructuredtext pygments ubuntu

Ubuntu 12.04 LTS comes with Python docutils version 0.8.1.

This version lacks support for ::code directives and some more features which prevents you from testing your reStructuredText document before uploading it to Github.

This little guide will help you to solve this problem by showing you the necessary steps to preview your document with the latest docutils version available in a sandboxed Python environment.

virtualenv - Virtual Python environments

The first step is to create a dedicated, enclosed environment for installing local, non system wide Python packages.

This requirement is met by using the great virtualenv package.

We strive for a local installation by first searching a proper place on your local hard disk and downloading & extracting the virtualenv package.

Please replace X.X.[X.] with the proper version constraint. At the time of writing this is 1.10.1.

curl -O[X.]tar.gz
tar xvfz virtualenv-X.X.[X.]tar.gz
python virtualenv-X.X[.X]/ current-docutils
virtualenv download + installation

Description of commands

Line 1: Downloading the proper archive package

Line 2: Extracting the downloaded archive package

Line 3: Creating a virtual environment named current-docutils in the current directory.

Activating the virtual environment

After creation of the virtual environment, change into the directory named current-docutils and execute the activation script.

Only when executing the activation script, you can ensure that your issued commands for installing Python packages are executed within the virtual environment.

cd current-docutils
source bin/activate
Execution of activation script

Installing docutils

As you're currently in a sandboxed Python environment, you can use the pip package manager to install the current docutils package without affecting the system wide Python/Python packages installation.

pip install docutils
Use pip to install Python packages

Installing pygments

As a developer you probably want to use the docutils ::code directive. This is only possible by installing the pygments package. The following command shows you how to achieve that.

pip install pygments
Install pygments for beautiful code syntax highlighting

Additional step: add a good looking stylesheet

This additional step allows you to use a great looking stylesheet for your documentation previews.

Open a new terminal window and issue the following command to download the great stylesheet made by Chad Skeeters.

curl -o cskeeters-rst2html-style.css
Download Chad Skeeters rst2html stylesheet

Generating the document preview

Switch back/close the terminal you've used to download the additional stylesheets and use the previous one which is hopefully in the state you've left it: pointing to and activated the generated Python virtual environment current-docutils.

Now it's the time to generate the HTML preview of your reStructuredText document.

Depending on if you're using the custom stylesheet of the previous step, leave out the as optional marked parameter --stylesheet.

python bin/ [--stylesheet=../cskeeters-rst2html-style.css] ~/projects/project1/README.rst ~/project/project1/README.html
Generate a local preview of your reStructuredText document

Image credits

© Jenny Rollo: Green Tree python


comments powered by Disqus