Directions for linking between chapters sections and linking to a reference in Restructured Text - ESCOMP/CTSM GitHub Wiki

Say you want to create a link to the References chapter from the Introduction chapter. You would do something like this in the Introduction rst file (CLM50_Tech_Note_Introduction.rst):

Scientific justification and evaluation of these parameterizations can be found in the referenced scientific papers (:ref:`rst_References`).

Then you would need to insert this statement at the top of the References rst file (CLM50_Tech_Note_References.rst):

.. _rst_References:

Update: All chapters now have the above link statement and you should only have to create the link in the desired rst file.

There are two ways to create a dynamic reference:

First, create a label using the following syntax:
(example taken from snow hydrology chapter)

.. _Snow Covered Area Fraction:

The key bits are ‘..’ at the front then a space, then a ‘_’ followed by whatever you want the label to be called. I recommend being more descriptive rather than less. The label ends with a ‘:’

After the label, leave a blank line, then write for example a subsection title

Snow Covered Area Fraction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To cross reference to that label use the following syntax:

section :numref:`Snow Covered Area Fraction`

Note: those aren’t quotation marks, they are (I think) ‘back quotes’, which on my keyboard are located with the tilde symbol on the upper left.

For a figure, use the following

.. _Figure three layer snow pack

.. Figure:: image1.png

  Example of three layer snow pack (:math:`snl=-3`).

Note: the caption must be indented relative to the ‘.. Figure::’ part. Tables are done similarly:

.. _Table Meltwater scavenging:

 .. table:: Meltwater scavenging efficiency for particles within snow   +------------------------------------------+-------------------+ | Species

The first line ‘.. _Table’ is the label, the second line ‘.. table::’ is the ‘table directive’ with its title,

And the 3rd line is the table itself, and must be indented at least 1 space relative to the table directive. When you stop indenting, the table ends and normal text occurs again.

To cross reference the figure, use the following:

:numref:`Figure three layer snow pack`

Note: there is no need to write ‘figure’ before the numref bit, it will be added automatically. You can have any text you’d like for the label, but I recommend beginning with ‘Figure’ to make it obvious what the reference is for when reading the rst files.

:numref: gives a numbered reference (surprise!). For the bibliographic references, the convention is to use the authors’ names, so use the following:

:ref:`Bonan (1996) <Bonan1996>`

The first bit, in this case the ‘Bonan (1996)’ can be whatever you want, i.e. it could be (Bonan 1996). The second bit, in the brackets, must be what is used to label the reference in the References rst file: CLM50_Tech_Note_References.rst.