Documentation¶

The compass documentation is generated using the Sphinx package and is written in reStructuredText format. We recommend this basic guide to reStructuredText in Sphinx.

Another easy way to get started is by taking a look at the existing source code for the documentation: https://github.com/MPAS-Dev/compass/tree/master/docs/

Each time you add a core, configuration or test case, the corresponding documentation must be included with the pull request to add the code. This includes documentation for both the User’s Guide and the Developer’s Guide. For examples, see:

Ocean core in the User’s Guide
baroclinic_channel configuration in the User’s Guide
Ocean core in the Developer’s Guide
baroclinic_channel configuration in the Developer’s Guide

Documentation for each core in the User’s guide should include a label with the name of the core:

.. _ocean:

Ocean core
==========

...

In the Developer’s Guide, labels have dev_ prepended to them:

.. _dev_ocean:

Ocean core
==========

...

Each configuration should have the core prepended to its label (in case multiple cores have the same configuration name), and each test case (if explicitly labeled) should have the core and configuration prepended to it. Thus, in the User’s guide, we have:

.. _ocean_baroclinic_channel:

baroclinic_channel
==================

...

.. _ocean_baroclinic_channel_default:

default
-------

And in the Developer’s guide, these become:

.. _dev_ocean_baroclinic_channel:

baroclinic_channel
==================

...

.. _dev_ocean_baroclinic_channel_default:

default
-------

Documentation for a core, configuration or test case in the User’s Guide should contain information that is needed for users who set up and run the test case, including:

Documentation for the MPAS core itself (if any)
A page for each configurations with a section for each test case:
- A citation or link where the configuration is defined (if any)
- A brief overview of the test cases within the configuration
- An image showing typical output from one of the test cases
- A list of (commented) config options that apply to all test cases
- A (typically brief) description of each test case
A description of any common framework within the core that the configuration or test case pages may need to refer to. This should only include framework that users may need to be aware of, e.g. because of Config Files or namelist options they may wish to edit.
A description of each test suite, including which test cases are included

The Developer’s guide for each core should contain:

Relevant technical details about development specific to that core
A page for each configuration:
- A description of any development-specific details of that configuration
- A description of shared config, namelist and streams files
- A description of shared steps
- A description of any other shared framework code for the configuration
- A description of each test case and its steps
Technical details on the shared framework for the core

Finally, all functions in the configuration that are part of the public API (i.e. all functions that don’t start with an underscore) should be added to docs/<core>/api.rst:

baroclinic_channel
~~~~~~~~~~~~~~~~~~

.. currentmodule:: compass.ocean.tests.baroclinic_channel

.. autosummary::
   :toctree: generated/

   collect
   configure

   decomp_test.collect
   decomp_test.configure
   decomp_test.run

   ...

The Developer’s Guide also contains details on the framework shared across compass, so any updates to this framework should include relevant additions or modifications ot the documentation.

Docstrings¶

The Developer’s Guide includes a API reference that is automatically generated from the python code and the docstrings at the beginning of each function. compass uses docstrings in the Numpydoc format. A typical example looks like this:

def compute_land_ice_pressure_and_draft(ssh, modifySSHMask, ref_density):
    """
    Compute the pressure from and overlying ice shelf and the ice-shelf draft

    Parameters
    ----------
    ssh : xarray.DataArray
        The sea surface height (the ice draft)

    modifySSHMask : xarray.DataArray
        A mask that is 1 where ``landIcePressure`` can be deviate from 0

    ref_density : float
        A reference density for seawater displaced by the ice shelf

    Returns
    -------
    landIcePressure : xarray.DataArray
        The pressure from the overlying land ice on the ocean

    landIceDraft : xarray.DataArray
        The ice draft, equal to the initial ``ssh``
    """

The docstring must include a brief description of the function. Then, it includes a Parameters section with entries for each argument. The argument are always given on their own line with the type, separated by `` : `` (note the spaces on either side of the colon). The type should not be in code format (i.e. not in double back-quotes) because this interferes with Sphinx’s ability to link to the documentation for the type. In the example above, Sphinx will automatically find the API reference to xarray.DataArray within the xarray documentation (which is also written using sphinx). If an argument is a keyword argument (i.e. given with arg=value in the function declaration), the type should be followed by , optional, indicating that the argument will take on a default value if it is not supplied.

On the next lines after the argument and type, indented by 4 spaces, is a brief description of the argument. If the argument is optional and the default value is not obvious (e.g. arg=None is used as an indication that arg will be replaced by something else in the function), it should also be described. If the default value of the argument is obvious in the function declaration (e.g. arg=True), no further description is necessary.

Finally, if the function returns values, these need to be described in the same way as the parameters, with the name of the return values followed by a colon and the type, then a description, indented by 4 spaces.

Other sections such as Raises and Examples are optional.