rST Cheat Sheet

Use this cheat sheet as a quick reference to the correct header formats, tables, lists, and other essential elements of your documentation.

See also

For general rST tips, see:

Headers

Tip

Header underlines must be the same length as the title text.

Top-level (h1)

Document Title
==============

Second-level (h2)

Section Title
-------------

Third-level (h3)

Sub-Section Title
`````````````

Fourth-level (h4)

Sub-Section Title
~~~~~~~~~~~~~~~~~

Fifth-level (h5)

Sub-Section Title
^^^^^^^^^^^^^^^^^

Sixth-level (h6)

Sub-Section Title
*************

Line Breaks

Use blank lines to insert line breaks.

this:

Some text.

Some more text.

becomes this:

Some text.

Some more text.

Lists

Tip

Sphinx requires a blank line before the first list item and after the last. Blank lines between list items are optional.

Bullet Lists

this:

* Item 1
* Item 2

- Item 3
- Item 4

+ Item 5
+ Item 6

becomes this:

  • Item 1
  • Item 2
  • Item 3
  • Item 4
  • Item 5
  • Item 6

Numbered Lists

Tip

You can use either actual numbers or the number sign (#) for enumerated lists. The number sign creates auto-numbered lists.

this:

1. First
2. Second
#. Third
#. Fourth

becomes this:

  1. First
  2. Second
  3. Third
  4. Fourth

Tables

You can format tables in many ways. See this great example for all of the available options.

Simple Tables

this:

======  =====   =====
Col 1   Col 2   Col 3
-------------   -----
A       B       C
D       E       F
======  =====   =====


======  =====   =====
Col 1 & 2       Col 3
-------------   -----
A       B       C
D       E       F
======  =====   =====

======  =====   =====
Col 1   Col 2   Col 3
------  -----   -----
A       B       CD

                EF
======  =====   =====

becomes this:

Col 1 Col 2 Col 3
A B C
D E F
Col 1 & 2 Col 3
A B C
D E F
Col 1 Col 2 Col 3
A B

CD

EF

Grid Tables

this

+-------+--------+-------+
| Col 1 | Col 2  | Col 3 |
+=======+========+=======+
| A     | B      | C     |
+-------+--------+-------+
| D     | E      | F     |
+-------+--------+-------+

+-------+--------+-------+
| Col 1 & Col 2  | Col 3 |
+=======+========+=======+
| A     | B      | C     |
+-------+--------+-------+
| D     | E      | F     |
+-------+--------+-------+

becomes this:

Col 1 Col 2 Col 3
A B C
D E F
Col 1 & Col 2 Col 3
A B C
D E F

Cross-References

Sphinx lets you cross reference any section label from anywhere else in the same documentation set.

  1. Create a section label.

    .. _some-section-label:

  2. Reference the label.

    link text

This is particularly useful for avoiding broken links that can occur if content moves.

Code

Sphinx and rST have a number of options for creating code blocks. We prefer the code-block:: directive, which provides a robust set of options including line-numbering (:linenos:), line-emphasis (:emphasize-lines:), and language highlighting (automatic).

See also

sphinx-doc code-block directive

Example:

.. code-block:: python
   :linenos:

   >>> from f5.bigip import ManagementRoot
   >>> mgmt = ManagementRoot("bigip.example.com", "admin", "somepassword")
   >>> pools = mgmt.tm.ltm.pools.get_collection()
   >>> for pool in pools:
   >>> print pool.name

becomes

1
2
3
4
5
>>> from f5.bigip import ManagementRoot
>>> mgmt = ManagementRoot("bigip.example.com", "admin", "somepassword")
>>> pools = mgmt.tm.ltm.pools.get_collection()
>>> for pool in pools:
>>> print pool.name