More doc updates (#295)

Author: dcherian

doc/bounds.md

@@ -4,4 +4,8 @@
 
 # Bounds Variables
 
-See {py:attr}`Dataset.cf.bounds`, {py:func}`cf_xarray.bounds_to_vertices`,  {py:func}`cf_xarray.vertices_to_bounds` 
+See
+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`

doc/dsg.md

@@ -0,0 +1,34 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+```{eval-rst}
+.. currentmodule:: xarray
+```
+```{code-cell}
+---
+tags: [remove-cell]
+---
+import cf_xarray
+import numpy as np
+import xarray as xr
+xr.set_options(display_expand_data=False)
+```
+
+
+# Discrete Sampling Geometries
+
+`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}
+ds = xr.Dataset(
+    {"temp": ("x", np.arange(10))},
+    coords={"cast": ("x", np.arange(10), {"cf_role": "profile_id"})}
+)
+ds.cf["profile_id"]
+```
+

doc/index.rst

@@ -1,8 +1,3 @@
-.. cf_xarray documentation master file, created by
-   sphinx-quickstart on Mon Jun  1 06:30:20 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 |
 |
 
@@ -17,7 +12,7 @@ Welcome to ``cf_xarray``
 ========================
 
 ``cf_xarray`` mainly provides an accessor (``DataArray.cf`` or ``Dataset.cf``) that allows
-you to interpret CF attributes present on xarray objects.
+you to interpret `Climate and Forecast metadata convention <http://cfconventions.org/>`_ attributes present on `xarray <https://xarray.pydata.org>`_ objects.
 
 Installing
 ----------
@@ -38,7 +33,7 @@ or using ``conda``
    :caption: In-depth Examples
 
    examples/introduction
-   EarthCube 2021 <https://earthcube2021.github.io/ec21_book/notebooks/ec21_cherian_etal/DC_01_cf-xarray.html>
+   EarthCube 2021 demo <https://earthcube2021.github.io/ec21_book/notebooks/ec21_cherian_etal/DC_01_cf-xarray.html>
 
 
 .. toctree::
@@ -55,6 +50,7 @@ or using ``conda``
    units
    parametricz
    bounds
+   dsg
    geometry
    plotting
    custom-criteria

doc/selecting.md

@@ -13,6 +13,7 @@ kernelspec:
 ---
 tags: [remove-cell]
 ---
+import numpy as np
 import xarray as xr
 xr.set_options(display_expand_data=False)
 ```
@@ -45,6 +46,18 @@ The variable `airds.air` has `standard_name: "air_temperature"`, so we can use t
 airds.cf["air_temperature"]
 ```
 
+## By `cf_role`
+
+`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}
+ds = xr.Dataset(
+    {"temp": ("x", np.arange(10))},
+    coords={"cast": ("x", np.arange(10), {"cf_role": "profile_id"})}
+)
+ds.cf["profile_id"]
+```
+
 ## Associated variables
 
 `.cf[key]` will return a DataArray or Dataset containing all variables associated with the `key` including ancillary variables and bounds variables (if possible).

doc/whats-new.rst

@@ -4,6 +4,7 @@ What's New
 ----------
 v0.6.4 (unreleased)
 ===================
+- Significantly expanded and improved documention. By `Deepak Cherian`_.
 - integrate ``xclim``'s CF-compliant unit formatter. :pr:`278`. By `Justus Magin`_.
 - Fix dropping of bad variable names. :pr:`291`. By `Tom Vo`_.