Documentation
The polaris documentation is generated using the Sphinx package and is written in MyST format. We recommend these basic tips on using MyST in Sphinx.
Another easy way to get started is by taking a look at the existing source code for the documentation: https://github.com/E3SM-Project/polaris/tree/main/docs/
Each time you add a component or task, 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 component in the User’s Guide
baroclinic channel tasks in the User’s Guide
Ocean component in the Developer’s Guide
baroclinic_channel tasks in the Developer’s Guide
Documentation for each component in the User’s guide should include a label with the name of the component:
(ocean)=
# Ocean
...
In the Developer’s Guide, labels have dev- prepended to them:
(dev-ocean)=
# Ocean component
...
Each category of tasks (e.g. baroclinic channel) should have its own page in
the tasks subdirectory of the component. The label for the page should have
have the component name prepended (to make sure it’s unique), and each task
(if explicitly labeled) should have the component and category of tasks
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 component or task 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 component itself (if any)
A page for each category of tasks with a section for each task:
A citation or link where the test case that is the basis for the tasks is defined (if any)
A brief overview of the common characteristics of the tasks
An image showing typical output from one of the tasks
A list of (commented) config options that apply to all tasks
A (typically brief) description of each task
The following sections as described in the template: description, mesh, vertical grid, initial conditions, forcing, time step, config, and cores
A description of any common framework within the component that the test group or task 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 suite, including which tasks are included
A template is available for documenting groups of related tasks in the User’s Guide:
The Developer’s guide for each component should contain:
Relevant technical details about development specific to that component
A page for each category of tasks:
A description of any development-specific details common to all tasks in this category
A description of shared config, namelist and streams files
A description of shared steps
A description of any other shared framework code shared between the tasks in that category
A description of each task and its steps
Technical details on the shared framework for the component
Finally, all functions in the tasks and their shared framework that are part of
the public API (i.e. all functions that don’t start with an underscore) should
be added to docs/<component>/api.md:
### baroclinic_channel
```{eval-rst}
.. currentmodule:: polaris.ocean.tasks.baroclinic_channel
.. autosummary::
:toctree: generated/
add_baroclinic_channel_tasks
forward.Forward
forward.Forward.compute_cell_count
forward.Forward.dynamic_model_config
init.Init
init.Init.setup
init.Init.run
...
```
The Developer’s Guide also contains details on the framework shared across polaris, 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. Polaris uses docstrings in the Numpydoc format. The text is in reStructuredText 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.