reStructuredText primer

reStructuredText (RST) is a lightweight markup language quite similar to Markdown. Although Markdown is more popular, RST has many benefits over Markdown when writing fully-fledged documentation projects. It’s more standardized, with more features for doc management, and is more extensible. RST makes use of many Sphinx directives for formatting content. For more information, see this Eric Holscher’s blog.

See Text editors: Write the source for information on how to configure RST syntax highlighting and other helpful features in some of the more common text editors. There are also RST templates for different types of topics available at RST templates.

This topic displays the RST syntax inside literal blocks so it can be viewed in the compiled HTML. The templates are formatted as you would use them–you must view the raw RST to see the syntax. The directives often require blank lines or particular indentation to style content correctly.

Use lowercase for all RST filenames and connect words using hyphens. For example, my-topic.rst.

Comparison to Markdown

The table below summarizes some of the more common formatting elements and how the syntax differs in Markdown and RST. Sphinx also has many directives, which instruct Sphinx to process text in particular ways (as a table, conditional text, etc.).

Markdown vs RST




Section heading

# Section title

Section title










External link

[Link text](

`Link text <>`_

There are tools, such as, to convert Markdown to plain RST (lacking any Sphinx-specific directives).

Helpful Sphinx documentation


All RST topics must appear in the docset table of contents. You can nest additional TOCs in child topics. List the files, without the .rst extension, as follows:

.. toctree::



All over/underlines must be at least as long as the heading text. Use the following formatting for each level of heading:

Topic title

H1 heading

H2 heading

H3 heading

At the point of H4 headings, consider breaking the topic up into smaller components.

Diagrams and images

If you want to include architecture diagrams or other diagrams in the documentation, you can create PNG files in any program you like, such as Visio or Adobe Illustrator. See for more information on how to insert images.

When adding colors to documentation (diagrams, etc.), the best practice is to use same color scheme values listed for website colors. Here are a few of the key colors with their hex and RGB values. This can be useful defining matching colors in Visio and other diagram, visual applications.

IDM branding colors




Dark Blue


0, 108, 166

Bright Blue


71, 200, 245

Official Orange


241, 129, 83

True Black


0, 0, 0

  • Use PNG files with transparent backgrounds.

  • For accessibility, always include alt text and be sure the information contained in the image is also in text.

  • Use :scale: to resize the image to an appropriate size.

  • Use the semantic caption and legend, not bold text or paragraphs.

Another option that can make creation and maintenance of diagrams easier is to make them using PlantUML. We include the Plantweb extension in our Sphinx configuration to enable PlantUML to be built in Sphinx documentation. For more information, see For more information on PlantUML syntax, see

Mathematical equations

If you need to include mathematical expressions in the spec, you can use LaTeX formatting using the math directive. To include mathematical expressions in the sentence, use something like:

:math:`v`, :math:`{\mu}`, and :math:`{\gamma}`.

For a math expression on a separate line, use something like the following:

.. math::

    \frac{dX}{dt} &= vN - \frac{\beta_0}{N}XY - \mu{X} \\
    \frac{dY}{dt} &= \frac{\beta_0}{N}XY - \gamma{Y} - \mu{Y} \\
    \frac{dZ}{dt} &= \gamma{Y} - \mu{Z}

See and

Code samples

You can format create code formatting inline with double backticks. To present longer code samples, you have several options. The simplest is a double colon followed by indented code. This will be formatted with Python syntax highlighting:

This is my introductory sentence::

   def my_func()

You can specify the language used to change the syntax highlighting as follows:

.. code-block:: json

      "key": 123

You can also pull in a separate code file to display. Include the relative path to the file as follows:

.. literalinclude:: ../json/file.json

If there’s an external URL that contains a code sample you want to display, you can use the remoteliteralinclude directive in the same way.


Sphinx has several options to create tables, but generally CSV tables are the easiest to set up, whether you use a separate CSV file or an embedded list of comma-separate values. For more information, see csv-table.


Use hyphens or asterisks for bulleted lists. If you use the number sign for numbered lists, Sphinx will automatically update the numbers. You can nest bulleted and numbered lists. For example:

#. Step 1.
   * Bullet
   * Bullet
#. Step 2.
#. Step 3.

You can also use definition lists as follows:

   Definition. Definitions that extend past a single line must
   be intended.

Glossary terms

On the first use of terms that our audience may not be familiar with, link to the glossary entry. Add new glossary entries and definitions in the glossary.rst topic using the definition list format. To link to the glossary entry, use:

:term:`glossary entry`

Notes and warnings

Use the note and warning admonitions syntax. Use notes for additional information and warnings when data loss or some other negative consequence may occur:

.. note::

   For more information.



Reusable content

Any reusable content should be a text file, not an RST file, and stored in a reuse folder.

The reuse/variables.txt file contains product and feature names, supported third-party software versions, and other short strings that are used extensively throughout the documentation and likely to be changed. It is specified as the RST epilog in the docset configuration files, meaning it is appended to the end of each topic. See replacement text for more information.

Variables define both the full form (for first use in a topic) and the short form or acronym (for all subsequent uses). Don’t try to pluralize variables or otherwise include them as part of a longer term. This can have unforeseen consequences depending on how naming changes in the future. Instead, create a new variable.

Other files in the reuse directory include commonly used warnings, notes, etc. that are reused for consistency and ease of updates. Pull these in using the include directive.


You can leave comments in files by beginning a line with two periods and a space. These comments will be completely stripped from the built HTML.