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 https://pypi.python.org/packages/source/v/virtualenv/virtualenv-X.X.[X.]tar.gz tar xvfz virtualenv-X.X.[X.]tar.gz python virtualenv-X.X[.X]/virtualenv.py current-docutilsvirtualenv 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/activateExecution of activation script
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 docutilsUse pip to install Python packages
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 pygmentsInstall 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 https://bitbucket.org/cskeeters/rst2html-style/raw/f30eaf6fe49640e547a76b54a4e1c7f11c6302f0/style.cssDownload 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/rst2html.py [--stylesheet=../cskeeters-rst2html-style.css] ~/projects/project1/README.rst ~/project/project1/README.htmlGenerate a local preview of your reStructuredText document
© Jenny Rollo: Green Tree python