reStructuredText is also called reST (refer to http://docutils.sourceforge.net/rst.html). It is a plain text markup language widely used in the Python community to document packages. The great thing about reST is that the text is still readable since the markup syntax does not obfuscate the text like LaTeX would.
Here's a sample of such a document:
===== Title ===== Section 1 ========= This *word* has emphasis. Section 2 ========= Subsection :::::::::: Text.
reST comes in docutils, a package that provides a suite of scripts to transform a reST file to various formats, such as HTML, LaTeX, XML, or even S5, Eric Meyer's slide show system (refer to http://meyerweb.com/eric/tools/s5).
Writers can focus on the content and then decide how to render it, depending on the needs. For instance, Python itself is documented into reST, which is then rendered in HTML to build http://docs.python.org, and in various other formats.
The minimum elements one should know to start writing reST are:
- Section structure
- Lists
- Inline markup
- Literal block
- Links
This section is a really fast 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:
$ more text.txt Title ===== content. $ rst2html.py text.txt <?xml version="1.0" encoding="utf-8" ?> ... <html ...> <head> ... </head> <body> <div class="document" id="title"> <h1 class="title">Title</h1> <p>content.</p> </div> </body> </html>
The document's title and its sections are underlined using nonalphanumeric characters. They can be overlined and underlined, and a common practice is to use this double markup for the title and keep a simple underline for sections.
The most used characters to underline a section title are in the following order of precedence: =, -, _, :, #, +, ^.
When a character is used for a section, it is associated with its level and it has to be used consistently throughout the document.
Consider the following code for example:
============== Document title ============== Introduction to the document content. Section 1 ========= First document section with two subsections. Note the ``=`` used as heading underline. Subsection A ------------ First subsection (A) of Section 1. Note the ``-`` used as heading underline. Subsection B ------------ Second subsection (B) of Section 1. Section 2 ========= Second section of document with one subsection. Subsection C ------------ Subsection (C) of Section 2.
Figure 1 reStructuredText converted to HTML and rendered in the browser
reST provides readable syntax for bullet lists, enumerated lists, and definition lists with autoenumeration features:
Bullet list:
- one
- two
- three
Enumerated list:
1. one
2. two
#. auto-enumerated
Definition list:
one
one is a number.
two
two is also a number.
Figure 2 Different types of lists rendered as HTML
The text can be styled using an inline markup:
*emphasis*: Italics**strong emphasis**: Boldface``inline preformated``: Inline preformatted text (usually monospaced, terminal-like)`a text with a link`_: This will be replaced by a hyperlink as long as it is provided in the document (see in the Links section)
When you need to present some code examples, a literal block can be used. Two colons are used to mark the block, which is an indented paragraph:
This is a code example
::
>>> 1 + 1
2
Let's continue our textNotice that the colon characters can be put in a text line. In that case, they will be replaced by a single colon in various rendering formats:
This is a code example::
>>> 1 + 1
2
Let's continue our textIf you don't want to keep a single colon, you can insert a space between the leading text and ::. In that case, :: will be interpreted and totally removed.
Figure 3 Code samples in reST rendered as HTML
A text can be changed into an external link with a special line starting with two dots, as long as it is provided in the document:
Try `Plone CMS`_, it is great ! It is based on Zope_. .. _`Plone CMS`: http://plone.org .. _Zope: http://zope.org
A usual practice is to group the external links at the end of the document. When the text to be linked contains spaces, it has to be surrounded with ` (backtick) characters.
Internal links can also be used by adding a marker in the text:
This is a code example
.. _example:
::
>>> 1 + 1
2
Let's continue our text, or maybe go back to
the example_.Sections are also targets that can be used:
============== Document title ============== Introduction to the document content. Section 1 ========= First document section. Section 2 ========= -> go back to `Section 1`_