reStructuredText Primer

By: Cam Wohlfeil
Published: 2018-09-09 2300 EDT
Modified: 2018-11-01 1200 EDT
Category: General
Tags: restructuredtext

reStructuredText (reST) is a markup language designed to be easy to write, similar to Markdown, but with more capabilities. I don't recommend most people use it, as Markdown is a better choice most of the time. It's easier to write and supported almost everywhere. Luckily, the site generator I use to create this blog supports both with no issues so I write normal posts in Markdown and use reST for posts with lots of code.

When trying to learn reST I had complaints with most of the primers out there, either for being too technical or too short, so this is my attempt at one that works better for me. The sections are in order of the likelihood of needing them, but I suggest you at least read through to Explicit Markups.

Paragraphs and Inline Markup

Paragraphs are just chunks of text separated by blank lines. Indentation matters.

Inline markup cannot be nested, start or end with whitespace ( text ), and it must be separated from surrounding text by spaces. If asterisks or backquotes appear in the text and could be confused with inline markup they have to be escaped with a backslash (thisis\ one\ word). ::

*italic* 
**bold**
``code samples``

Links

Full URL link: https://github.com
Inline text link: `Github <https://github.com/>`_
Inline text link w/ target: `Github`_
.. _Github: https://github.com/

Internal links are a bit more complicated, but can be accomplished with reST labels. If you place a label directly before a section title or figure, you can reference to it like so:

.. _my-reference-label:

Section to cross-reference
--------------------------

Text of the section. Reference the section with :ref:`my-reference-label`.

The link text will be the section title. This works just as well when section and reference are in different source files. Automatic labels also work with figures and tables with explicit captions. Labels that aren’t placed before a section title can still be referenced, but you must give the link an explicit title.

:ref:`Link title <label-name>`.

Label names must be globally unique. Reference labels must start with an underscore. When referencing a label, the underscore must be omitted. Using ref is advised over standard links to sections like Section title`_ because it works across files, when section headings are changed, it will raise warnings if incorrect, and works for all builders that support cross-references.

Images

.. image:: gnu.png
        (options)

Options can be used to set the image size, alt text, etc. See the Primer link below for more details.

Headings and Sections

Section headers are created by underlining the section title with a punctuation character, at least as long as the text. Overlining is optional. ::

=================
This is a heading
=================

There are no heading levels assigned to certain characters, the structure is determined from the succession of headings. This convention is used in Python’s Style Guide:

When writing a post, I tend to use:

Lists

Nested lists are possible, but they must be separated from the parent list by blank lines and indentation.

Unordered

* Item

    * Sub item

Ordered

1. Item

    1. Sub item

Ordered w/ auto numbering

#. Item

    #. Sub item

Definition list

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

   and can consist of multiple paragraphs

Code Blocks

Literal blocks

Identified by ending a paragraph with ::. The block must be surrounded by blank lines and indented.

This is a normal text paragraph. ::

   This paragraph is a code sample
   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

A normal text paragraph again.

.. code-block:: python

    Explicit markup format. This gives language information to the builder.

Doctest blocks

Interactive Python sessions cut-and-pasted into docstrings. They must end with a blank line and cannot end with with an unused prompt. They do not need the literal block syntax. 

>>> 1 + 1
2

Tables

There are more advanced features for tables, see the Primer link below.

=========== ========
Country     Capital
=========== ========
France      Paris
Japan       Tokyo
=========== ========

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Field lists

Sequences of fields commonly used in Python documentation.

:fieldname: Field content::

    def my_function(my_arg, my_other_arg):
        """A function just for me.

        :param my_arg: The first of my arguments.
        :param my_other_arg: The second of my arguments.

        :returns: A message (just for me, of course).
        """

Explicit Markup and Directives

Used for most constructs that need special handling. An explicit markup block begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation. There needs to be a blank line between explicit markup and normal paragraphs.

A directive is a generic block of explicit markup, like .. image. There are many of them that are only useful in certain circumstances, see the Primer link below for more info.

Footnotes and Citations

Footnotes

Use [#name]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading. You can explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_). 

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

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

Citations

Similar to footnotes but with a label that is not numeric or begins with #, and they are “global”, i.e. all citations can be referenced from all files.

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

Substitutions

Pieces of text and/or markup referred to in the text by |name|. 

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

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

If you want to use substitutions for all documents, put them into rst_prolog, rst_epilog, or a separate file and include it using the include directive. Give the include file an extension different from other source files to avoid it being treated as a standalone document. There are some default substitutions, see the Primer_ for more info.

Comments

Every explicit markup block which isn’t a valid markup construct is a comment. 

.. This is a comment.
.. You can indent text after a comment start to form multiline comments.

   Still in the comment.

Special Characters

The easiest way to include special characters like em dashes or copyright signs is to directly write them as Unicode characters. Source files are assumed to be encoded in UTF-8 by default. You can change this, see the Primer link below for more info.

References: