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

Element

Markdown

RST

# Section title

Section title
=============


Italics

_italics_

*italics*

Bold

**bold**

**bold**

Monospace

code

code

[Link text](www.url.com)

Link text <www.url.com>_

There are tools, such as https://cloudconvert.com/md-to-rst, to convert Markdown to plain RST (lacking any Sphinx-specific directives).

TOC¶

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::

filename1
filename2


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

===========
Topic title
===========

==========

----------

~~~~~~~~~~


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 https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images 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

Color

Hex

RGB

Dark Blue

006CA6

0, 108, 166

Bright Blue

47C8F5

71, 200, 245

Official Orange

F18153

241, 129, 83

True Black

000000

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 https://plantweb.readthedocs.io/#sphinx-directives. For more information on PlantUML syntax, see https://plantuml.com/.

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}


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.

Tables¶

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.

Lists¶

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:

term1
Definition.
term2
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::



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.