Docs cleanup (#518)

* Docs cleanup

* More links

Author: dcherian

doc/bounds.md

@@ -4,12 +4,13 @@
 
 # Bounds Variables
 
-See
-
+```{seealso}
+1. [CF conventions on coordinate bounds](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#cell-boundaries)
 1. {py:attr}`Dataset.cf.bounds`,
 1. {py:func}`Dataset.cf.add_bounds`,
 1. {py:func}`cf_xarray.bounds_to_vertices`,
 1. {py:func}`cf_xarray.vertices_to_bounds`
+```
 
 `cf_xarray` supports parsing [coordinate bounds](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#cell-boundaries) as encoded in the CF `bounds` attribute. A useful feature for incomplete dataset is also the automatic bounds estimation possible through `cf.add_bounds`. This method will estimate the missing bounds by finding the middle points between elements of the given coordinate, but also by extrapolating to find the outer bounds of the grid. This linear estimation works well with rectilinear grids, but it is only a coarse approximation for curvilinear and simple irregular grids.
 

doc/dsg.md

@@ -23,6 +23,11 @@ xr.set_options(display_expand_data=False)
 
 # Discrete Sampling Geometries
 
+```{seealso}
+1. [CF conventions on Discrete Sampling Geometries](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#discrete-sampling-geometries)
+1. {py:attr}`Dataset.cf.cf_roles`
+```
+
 `cf_xarray` supports identifying variables by the [`cf_role` attribute](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#discrete-sampling-geometries).
 
 ```{code-cell}

doc/flags.md

@@ -15,6 +15,10 @@ kernelspec:
 
 # Flag Variables
 
+```{seealso}
+1. [CF conventions on flag variables and masks](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags)
+```
+
 `cf_xarray` has some support for [flag variables](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags), including flag masks.
 
 ## Flag Values

doc/geometry.md

@@ -88,7 +88,7 @@ cfxr.cf_to_shapely(ds_cf)
 ```
 
 This conversion adds coordinates that aren't in the `xr.DataArray` that we started with.
-By default these are called `crd_x` and `crd_y` unless `grid_mapping` is specified.
+By default these are called `'crd_x'` and `'crd_y'` unless `grid_mapping` is specified.
 
 ## Gotchas
 

doc/grid_mappings.md

@@ -13,10 +13,11 @@ kernelspec:
 
 # Grid Mappings
 
-See
-
-1. {py:attr}`Dataset.cf.grid_mapping_names`,
+```{seealso}
+1. [CF conventions on grid mappings and projections](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#grid-mappings-and-projections)
+1. {py:attr}`Dataset.cf.grid_mapping_names`
 1. {py:attr}`DataArray.cf.grid_mapping_name`
+```
 
 `cf_xarray` understands the concept of coordinate projections using the [grid_mapping](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#grid-mappings-and-projections) attribute convention. For example, the dataset might contain two sets of coordinates:
 

doc/parametricz.md

@@ -22,6 +22,12 @@ xr.set_options(display_expand_data=False)
 
 # Parametric Vertical Coordinates
 
+```{seealso}
+1. [CF conventions on parametric vertical coordinates](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#parametric-vertical-coordinate)
+2. {py:meth}`Dataset.cf.decode_vertical_coords`
+3. {py:attr}`Dataset.cf.formula_terms`
+```
+
 `cf_xarray` supports decoding [parametric vertical coordinates](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#parametric-vertical-coordinate) encoded in the `formula_terms` attribute using {py:meth}`Dataset.cf.decode_vertical_coords`. Right now, only the two ocean s-coordinates and `ocean_sigma_coordinate` are supported, but support for the [rest](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#parametric-v-coord) should be easy to add (Pull Requests are very welcome!).
 
 ## Decoding parametric coordinates

doc/selecting.md

@@ -22,7 +22,15 @@ xr.set_options(display_expand_data=False)
 
 # Selecting DataArrays
 
-A second powerful feature of `cf_xarray` is the ability select DataArrays using special "CF names" like the "latitude", or "longitude" coordinate names, "X"  or "Y" axes names, oreven using the `standard_name` attribute if present.
+```{seealso}
+CF conventions on
+1. [coordinate variables](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#coordinate-types)
+1. [cell bounds and measures](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#_data_representative_of_cells)
+1. [standard name](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#standard-name)
+1. [ancillary data](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#ancillary-data)
+```
+
+A powerful feature of `cf_xarray` is the ability select DataArrays using special "CF names" like the "latitude", or "longitude" coordinate names, "X"  or "Y" axes names, oreven using the `standard_name` attribute if present.
 
 To demonstrate this, let's load a few datasets
 

doc/sgrid_ugrid.md

@@ -9,6 +9,11 @@ kernelspec:
 
 # SGRID / UGRID
 
+```{seealso}
+1. [SGRID conventions](https://sgrid.github.io/sgrid/)
+1. [UGRID conventions](http://ugrid-conventions.github.io/ugrid-conventions/)
+```
+
 ## SGRID
 
 `cf_xarray` can parse the attributes on the `grid_topology` variable to identify dimension names with axes names `X`, `Y`, `Z`.

doc/units.md

@@ -10,9 +10,13 @@ hide-toc: true
 
 # Units
 
+```{seealso}
+1. [CF conventions on units](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units)
+```
+
 The xarray ecosystem supports unit-aware arrays using  [pint](https://pint.readthedocs.io) and [pint-xarray](https://pint-xarray.readthedocs.io). Some changes are required to make these packages work well with [UDUNITS format recommended by the CF conventions](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#units).
 
-`cf_xarray` makes those recommended changes when you `import cf_xarray.units`. These changes allow pint to parse and format UDUNIT units strings, and add several custom units like `degrees_north`, `psu` etc.
+`cf_xarray` makes those recommended changes when you `import cf_xarray.units`. These changes allow pint to parse and format UDUNIT units strings, and add several custom units like `degrees_north` for latitude, `psu` for ocean salinity, etc.
 
 ## Formatting units