1.10.7. 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:
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.7.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
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.7.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-referencesSection headings, number:
:numref:`rst-cross-references`→ 1.10.7.2. Note that, unlikenumreffor 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.1Figure, 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.1Equation, 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.7.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.7.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.7.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.