-
Notifications
You must be signed in to change notification settings - Fork 443
Closed
Labels
Area: DocsAffects documentationAffects documentationType: MaintenanceUpdates and clean ups (but not wrong)Updates and clean ups (but not wrong)good first issueStraightforward issues suitable for new and inexperienced contributors to the projectStraightforward issues suitable for new and inexperienced contributors to the project
Milestone
Description
Right now the documentation for parameters for advection looks like:
Parameters
----------
scalar : `pint.Quantity` or `xarray.DataArray`
Array (with N-dimensions) with the quantity to be advected. Use `xarray.DataArray` to
have dimension ordering automatically determined, otherwise, use default
[..., Z, Y, X] ordering or specify \*_dim keyword arguments.
u, v, w : `pint.Quantity` or `xarray.DataArray` or None
N-dimensional arrays with units of velocity representing the flow, with a component of
the wind in each dimension. For 1D advection, use 1 positional argument (with `dx` for
grid spacing and `x_dim` to specify axis if not the default of -1) or use 1 applicable
keyword argument (u, v, or w) for proper physical dimension (with corresponding `d\*`
for grid spacing and `\*_dim` to specify axis). For 2D/horizontal advection, use 2
positional arguments in order for u and v winds respectively (with `dx` and `dy` for
grid spacings and `x_dim` and `y_dim` keyword arguments to specify axes), or specify u
and v as keyword arguments (grid spacings and axes likewise). For 3D advection,
likewise use 3 positional arguments in order for u, v, and w winds respectively or
specify u, v, and w as keyword arguments (either way, with `dx`, `dy`, `dz` for grid
spacings and `x_dim`, `y_dim`, and `vertical_dim` for axes).
dx, dy, dz: `pint.Quantity` or None, optional
Grid spacing in applicable dimension(s). If using arrays, each array should have one
item less than the size of `scalar` along the applicable axis. If `scalar` is an
`xarray.DataArray`, these are automatically determined from its coordinates, and are
therefore optional. Required if `scalar` is a `pint.Quantity`. These are keyword-only
arguments.
x_dim, y_dim, vertical_dim: int or None, optional
Axis number in applicable dimension(s). Defaults to -1, -2, and -3 respectively for
(..., Z, Y, X) dimension ordering. If `scalar` is an `xarray.DataArray`, these are
automatically determined from its coordinates. These are keyword-only arguments.It's ok, but there are a lot of details in the parameters that might be better done in the block above generally describing the function. The problem, though, is what happens in the web docs:
That wall of repeated chunks of indecipherable text just isn't useful to anyone.
When fixing this we should also add our mathematical definition of advection to the Notes section.
jthielen
Metadata
Metadata
Assignees
Labels
Area: DocsAffects documentationAffects documentationType: MaintenanceUpdates and clean ups (but not wrong)Updates and clean ups (but not wrong)good first issueStraightforward issues suitable for new and inexperienced contributors to the projectStraightforward issues suitable for new and inexperienced contributors to the project
Type
Projects
Status
Done
