reStructuredText cheat sheet

This cheat sheet explains how to use common reStructuredText formatting with the Sphinx documentation generator.

Headings

Start each section in a page with a heading. Use H1 for the page’s title, H2 for the page’s sections and H3 for the subsections.

==========
Header One
==========

Header Two
==========

Header Three
------------

Header Four
^^^^^^^^^^^

Header Five
"""""""""""

NOTE: The lines below and above a header must be at least the length of the text.

NOTE: H4 and H5 are discouraged and rarely used.

NOTE: Sphinx will actually accept any header style it encounters first as H1, the next as H2, and so on, but we prefer to use these styles for consistency.

Tables of contents

We use two types of tables of contents (TOCs):

  1. TOCTREE: This organizes the pages and creates a nested list of links to each page in the left navigation.
  2. CONTENTS: This creates a nested list of links to sections of the current page as in-page navigation.

Sphinx keeps pages in a tree data structure where each node is a page. The pages that have child pages list them with the .. toctree:: directive. The left navigation that links to each page is built from these lists.

By default the .. toctree:: directive creates both left navigation and in-page navigation links to the child pages. Using .. toctree:: with the :hidden: option creates left navigation only.

Sphinx requires that the toctree lists include all pages. If a page is not in any toctree list, it is a page with no parent page, or an “orphan” page, and the Sphinx build will fail with an error. If for some reason a page must be in the documentation and must not be in the left navigation, the :orphan: directive can be added at the top of that page so that Sphinx will build without errors. Please avoid the :orphan: directive as much as possible.

The optional directive .. contents:: will automatically scan the headers in a page and build an in-page nested table of contents from them. In-page links to the sections of a page make it easier for users to read long pages.

A .. contents:: directive may use the depth option to limit the depth of the nested list. For example, :depth: 2 will build a table of contents that only shows the highest two levels of headers. Use this in pages with many headers to keep the table of contents from being too long and unwieldy.

The Detailed reStructuredText and Sphinx example file includes more information and examples on contents and toctree.

Code formatting

Use fixed width or monospace text for inline code. EXAMPLE:

Use ``cd tmp`` to change to the ``tmp`` directory.

Use cd tmp to change to the tmp directory.

Use the .. code-block:: directive for blocks of code. EXAMPLE:

.. code-block:: python

    for i in range(10):
        print(i)
for i in range(10):
    print(i)

Code blocks can use the types python rst yaml bash none and more.

Lists

Use “#” for ordered (numbered) lists and “*” for unordered lists. EXAMPLES:

#. First item
#. Second item
  1. First item
  2. Second item
* Begin your list
* Split long list items across any
  number of lines
* Continue your list

  * Use nested lists when appropriate
  * Make sure the spacing is correct

* Finish your list.
  • Begin your list
  • Split long list items across any number of lines
  • Continue your list
    • Use nested lists when appropriate
    • Make sure the spacing is correct
  • Finish your list.

Images

Insert images with the .. figure:: directive.

To be sure there is enough space between an image and the text after it, insert a “pipe” or “vertical bar” character (“|”) after each image. These may also be inserted anywhere else to add extra space.

EXAMPLE:

.. figure:: /img/rst-cheatsheet-earth.jpg

   Caption goes here.

|

Text after the image goes here.

To insert a figure with no caption, replace the caption with an empty comment (".."):

.. figure:: /img/rst-cheatsheet-earth.jpg

   ..

|

Text after the image goes here.
../_images/rst-cheatsheet-earth.jpg

Caption goes here.


Text after the image goes here.

To insert a figure with no caption, replace the caption with an empty comment (”..”):

../_images/rst-cheatsheet-earth.jpg

Text after the image goes here.

Sphinx can also create tables, embed raw html, and more. For further information please see the Detailed reStructuredText and Sphinx example file.