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.
For more details check out the RST Primer
Heading 1 ######### There should be only 1 Heading 1 per topic, as the topic title. 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
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.
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`
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 also need to be indented by 3 or more spaces * Sub-item 2 #. Item 2
This codeblock is used for the following published list:
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.