reST Quick Start

reST is used to create the documentation for Iris. It is used to author all of the documentation content including use in docstrings where appropriate. For more information see Docstrings.

reST is a lightweight markup language intended to be highly readable in source format. This guide will cover some of the more frequently used advanced reST markup syntaxes, for the basics of reST the following links may be useful:

• https://www.sphinx-doc.org/en/master/usage/restructuredtext/

• https://packages.python.org/an_example_pypi_project/sphinx.html

Reference documentation for reST can be found at https://docutils.sourceforge.net/rst.html.

Creating Links

Basic links can be created with `Text of the link <https://example.com>`_ which will look like Text of the link

Documents in the same project can be cross referenced with the syntax :doc:`document_name` for example, to reference the “docstrings” page :doc:`docstrings` creates the following link Docstrings

References can be created between sections by first making a “label” where you would like the link to point to .. _name_of_reference:: the appropriate link can now be created with :ref:`name_of_reference` (note the trailing underscore on the label)

Cross referencing other reference documentation can be achieved with the syntax :py:class:`zipfile.ZipFile` which will result in links such as zipfile.ZipFile and numpy.ndarray.