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 heading	`# Section title`	Section title =============
Italics	`_italics_`	`italics`
Bold	`bold`	`bold`
Monospace	```code```	``code``
External link	`[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).

Helpful Sphinx documentation #

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

Headings #

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

See http://www.sphinx-doc.org/en/stable/ext/math.html and ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf.

Links #

Linking within the docset #

To link to other topics in the docset, use:

:doc:`file` (without the .rst extension)

You can also create references to sections within a topic using :ref:. See cross referencing for more information. For especially long topics, you can include a mini-TOC using:

.. contents:: Contents
   :local:

However, consider breaking the topic up into smaller components instead.

When mentioning Python code objects, such as mentioning classes or functions, use the following Python domain format to link to the code element(this example uses a class, see cross-referencing syntax for other object types):

*  On first instance, use :py:class:`simtools.Analysis.BaseAnalyzers.BaseAnalyzer`
   to include a link that shows the full domain
*  On subsequent instances, use :py:class:`~simtools.Analysis.BaseAnalyzers.BaseAnalyzer`
   to include a link that shows only the class name (notice the leading tilde)

External links #

See additional external link guidance.

Linking to other docsets #

IDM docsets are configured with intersphinx to enable linking to other Sphinx documentation sets without relying on external hyperlinking. This allows simpler syntax and link checking as part of the build process. The intersphinx mapping that defines the names and corresponding URLs for each docset is defined in the conf.py file.

Intersphinx links look like this:

:doc:`docset:topic`

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

   For more information.

Citations #

See http://www.sphinx-doc.org/en/stable/rest.html#citations.

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.

Comments #

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.