Quick Reference: Writing RST#

RST is very powerful and flexible. Below we provide a quick guide for how you can use it to write Open edX documentation.

Headings#

Heading 1
#########

There should be only 1 Heading 1 per topic, as the topic title.
The underline must match the length of the text above it.

Heading 2
*********

Heading 2s denote the main sections of a topic.

Heading 3
=========

Heading 3s denote subsections under Heading 2s.

Heading 4
---------

Heading 4s denote subsections under Heading 3s.

Heading 5
~~~~~~~~~

Heading 5s denote subsections under Heading 4s.
If you are this deep, consider splitting your document into multiple topics.

Inline Markup#

RST supports bold, italic, and mono-spaced characters. You can also make GUI elements appear as GUI elements.

Use double asterisks for **bold** text.

Use single asterisks for *italic* text.

Use double backticks for ``mono-spaced`` text.

Use the guilabel role for :guilabel:`GUI elements`

Lists#

You can make numbered, and bulleted lists that can nest arbitrarily, using the # symbol for ordered lists and * for unordered lists.

#. Item 1
                        # Need this blank line between items and sub-items
   * Sub-item 1         # Sub-items of ordered lists need to be indented by
   * Sub-item 2         # 3 spaces

#. Item 2

* Item 1

  #. Sub-item 1         # Sub-items of unordered lists need to be indented
  #. Sub-item 2         # by exactly 2 spaces

* Item 2

This codeblock is used for the following published list:

  1. Item 1

    • Sub-item 1

    • Sub-item 2

  2. Item 2

  • Item 1

    1. Sub-item 1

    2. Sub-item 2

  • Item 2

See the RST guide on lists for more detail.

Linking#

Directives#

RST can do a lot of things via directives. Here are some common ones:

.. warning::  This is a warning.

   It will be styled to stand-out in the documentation.

.. note:: This is a note.

   It will stand-out but not as much as a warning.

.. image:: path/to/image.png
   :alt: Alternative text for accessibility.

.. code-block:: python

   Some python code.

.. seealso::

   `Link to a thing <https://example.com>`_
      A brief description of the thing

   `Link to another thing <https://example.com/other>`_
      A brief description of another thing.

Learn More#

See also

A one-page reference document (PDF)

This reference document summarizes the above rules in an easy to print reference guide

RST Primer

The primer has a lot more detail about the concepts behind the markup.

RST Docs

If you want even more details, check out full RST Docs.