reStructuredText Cheet Sheet

syntax description for reStructuredText

Paragraphs

  • The paragraph is the most basic block in a reST document.
  • Separated by one or more blank lines.
  • Indentation is significant in reST, a paragraph must have same level of indentation.

Inline Markup

  • one asterisk means ltalic, *text* -> text
  • two asterisk means bold, **text** -> text
  • backquotes means code sample, ``text`` -> text

Restrictions

  • It cannot be nested.
  • It cannot start or end with whitespace: * text* is wrong.

Interpreted Text Roles

  • reST also allows for custom interpreted text roles.
  • Signify that the enclosed text should be interpreted in a specific way.
  • Sphinx uses this to provide semantic markup and cross-referencing of identifiers.
  • See Inline markup for roles added by Sphinx.

Lists and Quote-like Blocks

Basic Lists

  • bulleted lists use several signs (*, -, +, …)
  • numbered lists use number itself (1, 2, …)
  • auto-numbered lists use # sign
* bulleted list item
* bulleted list item

1. numbered list item
2. numbered list item
#. auto-numbered list item
#. auto-numbered list item
  • bulleted list item
  • bulleted list item
  1. numbered list item
  2. numbered list item
  3. auto-numbered list item
  4. auto-numbered list item

Nested Lists

  • nested lists must be seperated by blank lines
* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues
  • this is
  • a list
    • with a nested list
    • and some subitems
  • and here the parent list continues

Definition Lists

  • use indentation
term #1
  Definition of the term #1
  which must be indented

  multiple paragraphs are possible

term #2
  Definition of the term #2
term #1

Definition of the term #1 which must be indented

multiple paragraphs are possible

term #2
Definition of the term #2

Quoted Paragraphs

  • use a blank line and indentation
main paragraph

  quoted paragraphs
  quoted paragraphs

main paragraph (continues)

main paragraph

quoted paragraphs quoted paragraphs

main paragraph (continues)

Line Blocks

  • use a blank line and line breaks
main paragraph

| quoted paragraphs
| quoted paragraphs
|

main paragraph (continues)

main paragraph

quoted paragraphs
quoted paragraphs

main paragraph (continues)

Source Code

Literal Code Blocks

  • by ending with :: and indentation
normal text paragraph::

  source code paragraph except
  that the indentation is removed

  it can span multiple lines

nomal text paragraph (continues)

normal text paragraph:

source code paragraph except
that the indentation is removed

it can span multiple lines

nomal text paragraph (continues)

Smart Conversion Rules

  • if preceded by whitespace, :: is removed
  • if preceded by non-whitespace, :: is replaced by a single colon :
with colon::

  source code paragraph

without colon ::

  source code paragraph

with colon:

source code paragraph

without colon

source code paragraph

Syntax Highlighting

  • sphinx supports by
    • .. sourcecode:: language
    • .. code-block:: language
.. sourcecode:: cpp

  int main() {
    printf("Hello, World!");
    return 0;
  }

.. code-block:: python

  print('Hello, Python!')

int main() {
  printf("Hello, World!");
  return 0;
}

print('Hello, Python!')