reST comes in docutils, a package that provides a suite of scripts to transform a reST file into various formats, such as HTML, LaTeX, XML, or even S5, Eric Meyer's slide show system (refer to http://meyerweb.com/eric/tools/s5).
Here's a sample of such a document:
===== Title ===== Section 1 ========= This *word* has emphasis. Section 2 ========= Subsection :::::::::: Text.
Writers can focus on the content and then decide how to render it, depending on their needs. For instance, Python itself is documented in reST, which is then rendered in HTML and various other formats. You can visit the official Python documentation via http://docs.python.org.
The minimum elements you should know to start writing reST are these:
- Section structure
- Lists
- Inline markup
- Literal block
- Links
This section is a really quick overview of the syntax. A quick reference is available for more information at http://docutils.sourceforge.net/docs/user/rst/quickref.html, which is a good place to start working with reST.
To install reStructuredText, install docutils:
$ pip install docutils
For instance, the rst2html script provided by the docutils package will produce HTML output given a reST file:
$ cat text.txt Title =====
content. $ rst2html.py text.txt <?xml version="1.0" encoding="utf-8" ?> (...) <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> (...) </head> <body> <div class="document" id="title"> <h1 class="title">Title</h1> <p>content.</p> </div> </body> </html>
Let's take a look at all of the elements that we need to keep in mind in the next sections.