Add docs

Author: dcherian

cf_xarray/__init__.py

@@ -9,4 +9,6 @@
 from .options import set_options  # noqa
 from .utils import _get_version
 
+from . import geometry  # noqa
+
 __version__ = _get_version()

doc/api.rst

@@ -17,6 +17,16 @@ Top-level API
     encode_multi_index_as_compress
     decode_compress_to_multi_index
 
+Geometries
+----------
+.. autosummary::
+    :toctree: generated/
+
+    geometry.decode_geometries
+    geometry.encode_geometries
+    geometry.shapely_to_cf
+    geometry.cf_to_shapely
+
 .. currentmodule:: xarray
 
 DataArray

doc/geometry.md

@@ -50,7 +50,30 @@ da = xr.DataArray(
 geometries of the same type.
 ```
 
-Now we can take that `xr.DataArray` containing shapely geometries and convert it to cf:
+## Encode / Decode
+
+`cf-xarray` provides {py:func}`geometry.encode_geometries` and {py:func}`geometry.decode_geometries` to
+encode and decode xarray Datasets to/from a CF-compliant form that can be written to any array storage format.
+
+For example:
+
+```{code-cell}
+ds = da.to_dataset()
+encoded = cfxr.geometry.encode_geometries(ds)
+encoded
+```
+
+This dataset can then be written to any format supported by Xarray.
+To decode, reverse the process using {py:func}`geometry.decode_geometries`
+
+```{code-cell}
+decoded = cfxr.geometry.decode_geometries(encoded)
+ds.identical(decoded)
+```
+
+## Lower-level conversions
+
+Encoding a single DataArray is possible using {py:func}`cf_xarray.geometry.shapely_to_cf`.
 
 ```{code-cell}
 ds_cf = cfxr.shapely_to_cf(da)
@@ -94,6 +117,6 @@ By default these are called `crd_x` and `crd_y` unless `grid_mapping` is specifi
 
 For MultiPolygons with holes the CF notation is slightly ambiguous on which hole is associated
 with which polygon. This is problematic because shapely stores holes within the polygon
-object that they are associated with. `cf_xarray` assumes that the the shapes are interleaved
+object that they are associated with. `cf_xarray` assumes that the shapes are interleaved
 such that the holes (interior rings) are associated with the exteriors (exterior rings) that
 immediately precede them.