..
.. highlightlang:: rest
.. _rst-primer:
reStructuredText Primer
This section is a brief introduction to reStructuredText (reST) concepts and
syntax, intended to provide authors with enough information to author documents
productively. Since reST was designed to be a simple, unobtrusive markup
language, this will not take too long.
.. seealso::
The authoritative `reStructuredText User Documentation
<http://docutils.sourceforge.net/rst.html>`_. The "ref" links in this
document link to the description of the individual constructs in the reST
reference.
Paragraphs
The paragraph (:duref:`ref <paragraphs>`) is the most basic block in a reST
document. Paragraphs are simply chunks of text separated by one or more blank
lines. As in Python, indentation is significant in reST, so all lines of the
same paragraph must be left-aligned to the same level of indentation.
.. _inlinemarkup:
Inline markup
The standard reST inline markup is quite simple: use
* one asterisk: ``*text*`` for emphasis (italics),
* two asterisks: ``**text**`` for strong emphasis (boldface), and
* backquotes: ````text```` for code samples.
If asterisks or backquotes appear in running text and could be confused with
inline markup delimiters, they have to be escaped with a backslash.
Be aware of some restrictions of this markup:
* it may not be nested,
* content may not start or end with whitespace: ``* text*`` is wrong,
* it must be separated from surrounding text by non-word characters. Use a
backslash escaped space to work around that: ``thisis\ *one*\ word``.
These restrictions may be lifted in future versions of the docutils.
reST also allows for custom "interpreted text roles"', which signify that the
enclosed text should be interpreted in a specific way. Sphinx uses this to
provide semantic markup and cross-referencing of identifiers, as described in
the appropriate section. The general syntax is ``:rolename:`content```.
Standard reST provides the following roles:
* :durole:`emphasis` -- alternate spelling for ``*emphasis*``
* :durole:`strong` -- alternate spelling for ``**strong**``
* :durole:`literal` -- alternate spelling for ````literal````
* :durole:`subscript` -- subscript text
* :durole:`superscript` -- superscript text
* :durole:`title-reference` -- for titles of books, periodicals, and other
materials
See :ref:`inline-markup` for roles added by Sphinx.
Lists and Quote-like blocks
List markup (:duref:`ref <bullet-lists>`) is natural: just place an asterisk at
the start of a paragraph and indent properly. The same goes for numbered lists;
they can also be autonumbered using a ``#`` sign::
* This is a bulleted list.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
Nested lists are possible, but be aware that they must be separated from the
parent list items by blank lines::
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
Definition lists (:duref:`ref <definition-lists>`) are created as follows::