Tools for reStructuredText

Introduction

This document presents some of the tools available for working with reStructuredText.

It is divided in the following parts:

  • Editors: simple text editors providing syntax highlight for reST documents.
  • Builder and Converters: tools that automatically convert reST documents to other formats such as HTML, PDF, DOC, ODT, etc.
  • Integrated solutions: tools that allow the user to produce, build and convert documents using a single integrated environment.

Editors

reStructuredText documents are text files, and can be edited with any text editor or word processor (provided they are always saved as text files).

JEdit

jEdit is a FOSS text editor, written in Java (so it runs in Windows, Mac OS X, Linux, etc.). ReST is among the 211 languages supported natively by jEdit.

This document opened in jEdit.

Notepad++

Notepad++ is a FOSS text editor for MS Windows OS only.

reStructuredText is not among the languages natively recognised by Notepad++, but it can be added using a `User Defined Language File`_ (see install instructions below the list of available language files).

Follow the link to download the `ReST syntax file`_.

Notepad++ is simpler and more user friendly than jEdit.

This document opened in Notepad++.

ReText

ReText is a simple editor that reads your text with MarkDown or HTML markup and saves it as plain text, HTML or PDF. It is written in Python using Qt libraries.

Visual Studio Code

Visual Studio Code is a FOSS text editor, written in TypeScript (so it runs in Windows, Mac OS X, Linux, etc.). ReST is not among the languages natively supported by Visual Studio Code, but it can be added using an extension from LeXtudio.

This document opened in Visual Studio Code.

Builders and converters

Todo

Section on Builders and Converters such as Sphinx and Pandoc.

Sphinx

Sphinx is a Python documentation generator.

It requires Python, which is installed by default in Linux and Mac OS X systems. For Microsoft Windows systems, see Installing Python on Windows if you need help installing Python and two useful installation utilities (easy_install and pip).

After you have Python installed, simply use the following command (in a command window):

easy_install -U Sphinx

Elevated privileges (i.e. administration rights) should not be required.

The Sphinx builder can produce a number of output formats (e.g. HTML, PDF). PDF files can be produced using the LaTeX builder (more complicated) or using the a direct PDF builder called rst2pdf (see below).

Rst2Pdf

rst2pdf is a tool for transforming reStructuredText to PDF using ReportLab. To install rst2pdf on Windows you also need Python because rst2pdf is coded in python.

Rst2pdf uses ReportLab, which can be installed using:

easy_install reportlab

Again, in Windows, there may be a problem with the required Microsoft Visual Studio version. While running setup.py for package installations, Python 2.7 searches for an installed Visual Studio 2008. The solution is to define VS90COMNTOOLS variable to point to Tools directory of Visual Studio:

SET VS90COMNTOOLS=%VS100COMNTOOLS%

How to install rst2pdf on Windows?

  1. Download rst2pdf source from https://code.google.com/p/rst2pdf/downloads/list
  2. Unzip the file to an rst2pdf folder.
  3. Goto the the rst2pdf folder which contains setup.py file.
  4. Run python setup.py install command and it will be installed.
  5. To convert any .rst file to PDF file Run rst2pdf myfile.rst command and you are done.

Pandoc

Integrated solutions

ReST Editor for Eclipse

The ReST editor for Eclipse is a plug-in for the Eclipse IDE. If Sphinx is installed, it can also be used to create (and build) Sphinx projects from within Eclipse. The following presentation documents the use of the editor.

This ReST editor has several advantages, namely:

  • integrated spell-checking using Hunspell4Eclipse
  • contextual ReST syntax help
  • sections outline rearrangement
This document opened in the Eclipse ReST Editor.