SPHYINX RST CHEAT SHEET

A few example resources for cheat sheets:

• The Sublime and Sphyinx Guide

• reStructuredTest and Sphinx reference guide on documatt

Section headings

A heading in define by underlining the titile with a puncuation character that is at least as long as the title. The typical punction marks to use are = * # - ^ " and their usage should be consitent within a project.

For this wiki, we use the following:

• = for the top-level title, e.g., the title of this page.

• * for section headings, e.g., the “Section headings” heading of this section (that is a mouthful!).

• # for subsection headings.

• - for subsubsection headings.

Lists

Nested lists must be indent to the same level as the text starts. This is easy to miss when using an enumerated list because it requires an indent of 3 spaces instead of the usual 2 space indent.

The following does NOT properly produced an indented sub-list:

#. Main list item.

  #. This item is NOT indented enough.

The following DOES produced an indented sub-list:

#. Main list item.

   #. This item is indented enough, i.e., by 3 spaces.

Contents of an individual .rst file

The contents directive inserts a hyperlinked list of all the heading in that .rst file. The directive with its option:

.. contents:: Contents of this page
   :local:
   :backlinks: none
   :depth: 2

For which the results can be seen at the top of this page. The options are well explained on this documatt page, and summarised as:

• :local: exclude the top-level title of this page from the contents.

• :backlinks: none, remove hyperlinks from the section heading back to the contents.

• :depth: 2, specifies the depth to display in the contents.

Note

The contents directive must be used before the first sub-heading of the page.

Admonition directives

Admonition directives are those that provide a coloured box to highlight a particular type of information.

With custom title

The admonition directive allows you to give any title to the admonition block. The syntax is:

.. admonition:: Custom title for this admonition

  Contents go here for this admonition with a custom title.

Custom title for this admonition

Contents go here for this admonition with a custom title.

With pre-specified titles

The following are perhaps the two most common admonition directives with a specified title.

Note

This is a note admonition, created using the syntax .. note:: Contents of the note goes here.

Warning

This is a warning admonition, created using the syntax .. warning:: Contents of the warning goes here.

The other eight admonitions that are avaialble with a specified title are:

Attention

This is a attention admonition, created using the syntax .. attention:: Contents of goes here.

Caution

This is a caution admonition, created using the syntax .. caution:: Contents of goes here.

Danger

This is a danger admonition, created using the syntax .. danger:: Contents of goes here.

Error

This is a error admonition, created using the syntax .. error:: Contents of goes here.

Hint

This is a hint admonition, created using the syntax .. hint:: Contents of goes here.

Important

This is a important admonition, created using the syntax .. important:: Contents of goes here.

Tip

This is a tip admonition, created using the syntax .. tip:: Contents of goes here.

See also

This is a seealso admonition, created using the syntax .. seealso:: Contents of goes here.