Quick Reference: Writing RST

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.

Tip

Here’s a way to remember the symbols for heading levels: # has four lines, * has three lines, = has two lines, - has one line, and ~ has zero lines.

Note

RST allows you to use almost any symbol to underline headings, as long as you’re consistent between heading level. However, the way shown above is how headings should be defined in all Open edX documentation.

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:

Item 1
- Sub-item 1
- Sub-item 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#

Links off-site#

You can have `inline links <https://example.com>`_

`Indirect links`_ can be useful if you want to link to the same thing
multiple times, or if the url is really long and you want things to read more
cleanly.

.. _Indirect links: http://example.com/?lorem=Lorem%20ipsum%20dolor%20sit

Links within a document#

.. _some_location:

New Subsection Title
--------------------

Some text at this location.

Some other stuff that links back to :ref:`some_location`.

Links between rst documents#

Link to :doc:`file_b` in the same folder or :doc:`../file_c` in a different
folder or doc:`/file_d` relative to the root of the project.

By default it will use the title of the doc as the link text but you can
override that with doc:`other text </file_d>` if you want.

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.