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.
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.
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.
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?¶
- Download rst2pdf source from https://code.google.com/p/rst2pdf/downloads/list
- Unzip the file to an rst2pdf folder.
- Goto the the rst2pdf folder which contains setup.py file.
- Run
python setup.py install
command and it will be installed. - 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