sphinx-mmf-old / doc / rest.rst

The default branch has multiple heads

reStructuredText Primer



The paragraph (:rstref:`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.

Inline markup

The standard reST inline markup is quite simple: use

  • backquotes: ``text`` for code samples.


Be aware of some restrictions of this markup:

  • it may not be nested,

These restrictions may be lifted in future versions of the docutils.


Standard reST provides the following roles:

See :ref:`inline-markup` for roles added by Sphinx.

Lists and Quote-like blocks

List markup (:rstref:`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.


* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Definition lists (:rstref:`ref <definition-lists>`) are created as follows:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term


Quoted paragraphs (:rstref:`ref <block-quotes>`) are created by just indenting them more than the surrounding paragraphs.

Line blocks (:rstref:`ref <line-blocks>`) are a way of preserving line breaks:

| These lines are
| broken exactly like in
| the source file.

There are also several more special blocks available:

Source Code

Literal code blocks (:rstref:`ref <literal-blocks>`) are introduced by ending a paragraph with the special marker ::. The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines):


   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

The handling of the :: marker is smart:




Two forms of tables are supported. For grid tables (:rstref:`ref <grid-tables>`), you have to "paint" the cell grid yourself. They look like this:

| (header rows optional) |            |          |          |

Simple tables (:rstref:`ref <simple-tables>`) are easier to write, but limited: they must contain more than one row, and the first column cannot contain multiple lines. They look like this:

A      B      A and B
False  False  False
True   False  False
False  True   False
True   True   True


Section headers (:rstref:`ref <sections>`) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

This is a heading


  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • ", for paragraphs


Explicit Markup

"Explicit markup" (:rstref:`ref <explicit-markup-blocks>`) is used in reST for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives.



A directive (:rstref:`ref <directives>`) is a generic block of explicit markup. Besides roles, it is one of the extension mechanisms of reST, and Sphinx makes heavy use of it.

Docutils supports the following directives:

Do not use the directives :rstdir:`sectnum`, :rstdir:`header` and :rstdir:`footer`.

Directives added by Sphinx are described in :ref:`sphinxmarkup`.


.. function:: foo(x)
              foo(y, z)
   :bar: no

   Return a line of text input from the user.




reST supports an image directive (:rstdir:`ref <image>`), used like so:

.. image:: gnu.png





.. image:: gnu.*



For footnotes (:rstref:`ref <footnotes>`), use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the document after a "Footnotes" rubric heading, like so:


.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.



Standard reST citations (:rstref:`ref <citations>`) are supported, with the additional feature that they are "global", i.e. all citations can be referenced from all files. Use them like so:

Lorem ipsum [Ref]_ dolor sit amet.




reST supports "substitutions" (:rstref:`ref <substitution-definitions>`), which are pieces of text and/or markup referred to in the text by |name|. They are defined like footnotes with explicit markup blocks, like this:

.. |name| replace:: replacement *text*

or this:

.. |caution| image:: warning.png
             :alt: Warning!

See the :rstref:`reST reference for substitutions <substitution-definitions>` for details.

If you want to use some substitutions for all documents, put them into a separate file and include it into all documents you want to use them in, using the :rst:dir:`include` directive. Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.



Every explicit markup block which isn't a valid markup construct (like the footnotes above) is regarded as a comment (:rstref:`ref <comments>`). For example:

.. This is a comment.


   This whole indented block
   is a comment.

   Still in the comment.

Source encoding





