1.10.8. Tips for working with reStructuredText

If you've never used reStructuredText before, you should be aware that its syntax is pretty different from anything you've ever used before. We recommend the following resources as references for the syntax:

Sphinx's reStructuredText Primer
The Quick reStructuredText cheat sheet

Some especially useful bits:

On this page, we've compiled some supplemental information that might be helpful, including a list of common errors and their causes.

1.10.8.1. reStructuredText: Math 

You can write inline math like :math:`y = mx + b` → \(y = mx + b\). You can also write bigger equations on their own line that will automatically be numbered:

.. math::
  :label: equation for a line

  y = mx + b

(1.10.2)\[y = mx + b\]

Note (a) the leading spaces for each line after .. math:: and (b) the empty line after the label. If you don't include the :label: line, the equation will not be numbered.

reStructuredText math largely follows LaTeX syntax.

1.10.8.2. reStructuredText: Cross-references 

reStructuredText lets you define labels that can be cross-referenced as links elsewhere in the documentation. A label looks like .. _this-is-my-label: or .. _This is my label with CAPS and spaces:, on its own line surrounded by blank lines. The leading .. _ and trailing : are what tell rST "this line is a label." E.g.:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore   magna aliqua.

.. _this-is-my-label:

My cool information
^^^^^^^^^^^^^^^^^^^
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

You could then refer to that section with :XYZ:`this-is-my-label` (leaving off the leading .. _), where XYZ can be ref, numref, or eq (see examples below). This will create a link that, when clicked, takes the reader to the "My cool information" section.

Here are some examples. Note that the displayed link text will update automatically as needed (e.g., a section number or figure caption gets changed).

Section headings, text: :ref:`rst-cross-references` → reStructuredText: Cross-references
Section headings, number: :numref:`rst-cross-references` → 1.10.8.2. Note that, unlike numref for other things mentioned here, "Section" is not automatically prepended to the section number in the link text.
Table, text: :ref:`Table Crop plant functional types` → Crop plant functional types (PFTs) included in CLM5BGCCROP.
Table, number: :numref:`Table Crop plant functional types` → Table 2.27.1
Figure, text (uses entire caption): :ref:`Figure CLM subgrid hierarchy` → Configuration of the CLM subgrid hierarchy. Box in upper right shows hypothetical subgrid distribution for a single grid cell. Note that the Crop land unit is only used when the model is run with the crop model active. Abbreviations: TBD – Tall Building District; HD – High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C – Crop, V – Vegetated, PFT – Plant Functional Type, Irr – Irrigated, UIrr – Unirrigated. Red arrows indicate allowed land unit transitions. Purple arrows indicate allowed patch-level transitions.
Figure, number: :numref:`Figure CLM subgrid hierarchy` → Figure 2.2.1
Equation, number: :eq:`equation for a line` → (1.10.2). The parentheses in the link text seem unavoidable, and there seems to be no way to refer to have the link show the label text or anything else aside from the number.

You can have any link (except for equations) show custom text by putting the referenced label at the end in <angled brackets>. E.g., :ref:`Diagram of CLM subgrid hierarchy<Figure CLM subgrid hierarchy>` → Diagram of CLM subgrid hierarchy.

Note that this is necessary for labels that aren't immediately followed by a section heading, a table with a caption, or a figure with a caption. For instance, to refer to labels in our bibliography, you could do :ref:`(Bonan, 1996)<Bonan1996>` → (Bonan, 1996).

1.10.8.3. reStructuredText: Comments 

If you want to add some text that's only visible in the documentation source file, you can use the reStructuredText comment syntax:

..
  This will not appear on the webpage or even anywhere in the generated HTML.

Make sure to include at least one empty line after the comment text.

1.10.8.4. reStructuredText: Tables 

Tables defined with the :table: directive can be annoying because they're very sensitive to the cells inside them being precisely the right widths, as defined by the first ==== strings. If you don't get the widths right, you'll see "Text in column margin" errors. Instead, define your tables using the :list-table: directive.

If you already have a table in some other format, like comma-separated values (CSV), you may want to check out the R package knitr. Its kable command allows automatic conversion of R dataframes to tables in reStructuredText and other formats.

1.10.8.5. reStructuredText: Admonitions (e.g., warning, tip)

Admonitions are rendered as special "call-out" boxes. The general syntax is:

.. admonition:: This is the title of a generic admonition

  It needs a title specified. Synonyms you can put in the ``{}`` instead of ``admonition`` include ``note`` and   ``seealso``; if you use one of those, you don't need to specify a title.

This is the title of a generic admonition

It needs a title specified. Synonyms you can put in the {} instead of admonition include note and seealso; if you use one of those, you don't need to specify a title.

There are also a number of built-in admonition types that get their own special rendering:

.. attention::

  The reader should pay special attention to this. Synonyms you can put in the ``{}`` instead of ``attention`` include ``caution`` and ``warning``.

Attention

The reader should pay special attention to this. Synonyms you can put in the {} instead of attention include caution and warning.

.. danger::

  This tells the reader about something dangerous. You can also put ``error`` in the ``{}`` instead of ``danger``.

Danger

This tells the reader about something dangerous. You can also put error in the {} instead of danger.

.. hint::

  Here's a hint. Synonyms you can put in the ``{}`` instead of ``hint`` include ``important`` and ``tip``.

Hint

Here's a hint. Synonyms you can put in the {} instead of hint include important and tip.

1.10.8.6. reStructuredText: Embedding a different reStructuredText file 

.. include:: embed-example-rst.rst

Becomes:

Everything in this paragraph is just the contents of doc/source/users_guide/working-with-documentation/embed-example-rst.rst. It's in the same directory as the "Tips for working with reStructuredText" source file, so we only had to specify the filename. If it were in a different directory, we would specify the path relative to "Tips for working with reStructuredText". (Note that this file does NOT follow the "no line breaks within paragraphs" style convention; this is purely for readability of the embedded text.)

You can also embed literal contents of any file without the rendering:

.. literalinclude:: embed-example-rst.rst
   :language: restructuredtext

That becomes the literal contents (note syntax highlighting):

Everything in this paragraph is just the contents of
``doc/source/users_guide/working-with-documentation/embed-example-rst.rst``. It's in the same
directory as the "Tips for working with reStructuredText" source file, so we only had to
specify the filename. If it were in a different directory, we would specify the path
relative to "Tips for working with reStructuredText". (Note that this file does NOT follow
the "no line breaks within paragraphs" style convention; this is purely for readability of
the embedded text.)

You can also get fancy:

.. literalinclude:: embed-example-python.py
   :language: python
   :start-at: print
   :linenos:
   :lineno-match:

Becomes:

print("Hello world")
my_list = ["foo", "bar"]

See the Sphinx documentation for more options to the literalinclude directive.

1.10.8.7. reStructuredText: Text superscripts and subscripts 

Note that these instructions apply to text (i.e., not in inline or block math).

Superscripts

Incorrect: Fe:sup:`3+` becomes Fe:sup:3+
Incorrect: Fe :sup:`3+` becomes Fe ³⁺ (note extraneous space)
Correct: Fe\ :sup:`3+` becomes Fe³⁺

Subscripts

Incorrect: CO:sub:`2` becomes CO:sub:2
Incorrect: CO :sub:`2` becomes CO ₂ (note extraneous space)
Correct: CO\ :sub:`2` becomes CO₂

1.10.8.8. reStructuredText: Common error messages and how to handle them 

See Common docs errors: reStructuredText.