reStructuredText

reStructuredText (reST) is a markup language. The developers of many projects, including Python, use it to write documentation. It’s also what I’m using to write this website. It has unobtrusive syntax similar to Markdown, while supporting many things you would otherwise need HTML for.

I’ll be primarily referencing the reStructuredText Primer.

The basics

If you’ve written Markdown before, the basic concept is similar. A reStructuredText document is a plain text file, typically with the .rst file extension. A paragraph can continue across multiple lines, with a blank line between paragraphs.

Headings

A heading is a line of text underlined, and optionally overlined, with a punctuation symbol of your choice. As long as you’re consistent about what style you use for each level heading, they can be pretty much anything you want, though there are conventions you can follow if you like. If you’re wondering, this is what I use:

=========
Heading 1
=========

~~~~~~~~~
Heading 2
~~~~~~~~~

Heading 3
---------

I haven’t used a fourth-level heading yet, but I’d probably underline it with carets.

Links

Mark up the text within a paragraph that you want a link attached to, and put the link itself after the paragraph.

This is the first paragraph. Here is an `example of a link`_.
It will become clickable when the page is rendered.

.. _`example of a link`: https://example.com/

Internal links

In Sphinx (the static site generator I use), headings generate an anchor similarly to how they do in Markdown on many platforms.

Footnotes

There are a few different ways to use footnotes, but here’s the one I find most flexible.

Here is a reference to the first footnote[#example]_. When the
page is rendered, it will be labeled as "[1]". This is a
reference to a different footnote[#another]_, which will be
labeled as "[2]". This one refers to the first footnote
again[#example]_, so it will also be labeled "[1]".

.. rubric:: Footnotes

.. [#example] https://example.com/
.. [#another] This is another footnote.

Note

The .. rubric:: directive creates a heading that won’t appear in the table of contents.

Formatted blocks

Code

The blank line between the code-block:: directive and the beginning of the actual code is necessary, as is the indentation of the actual code block. Specifying the language and caption are optional.

.. code-block:: python
  :caption: hello.py

  name = 'reST'
  print('Hello ' + name + '!')

Tip

Syntax highlighting can be applied for any of the languages Pygments supports, and other formatting options are available.

Notices

Any of the following keywords can be used. Themes may have their own styles for each.

• note

• tip

• hint

• seealso

• attention

• important

• caution

• danger

• warning

• error

.. attention:: This is a message.
  This text is part of the same message.

This is a new paragraph.