Add roadmap and design info.

Author: dcherian

cf_xarray/accessor.py

@@ -6,6 +6,7 @@
 import xarray as xr
 from xarray import DataArray, Dataset
 
+#: Classes wrapped by cf_xarray.
 _WRAPPED_CLASSES = (
     xr.core.resample.Resample,
     xr.core.groupby.GroupBy,
@@ -14,9 +15,13 @@
     xr.core.weighted.Weighted,
 )
 
-
+#:  `axis` names understood by cf_xarray
 _AXIS_NAMES = ("X", "Y", "Z", "T")
+
+#:  `coordinate` types understood by cf_xarray.
 _COORD_NAMES = ("longitude", "latitude", "vertical", "time")
+
+#:  Cell measures understood by cf_xarray.
 _CELL_MEASURES = ("area", "volume")
 
 # Define the criteria for coordinate matches

doc/contributing.rst

@@ -0,0 +1,15 @@
+.. currentmodule:: cf_xarray
+
+Contributing
+--------------
+
+This section will be expanded later.
+
+.. autodata:: cf_xarray.accessor.coordinate_criteria
+.. autodata:: cf_xarray.accessor._WRAPPED_CLASSES
+
+The following names are "special"
+
+.. autodata:: cf_xarray.accessor._AXIS_NAMES
+.. autodata:: cf_xarray.accessor._COORD_NAMES
+.. autodata:: cf_xarray.accessor._CELL_MEASURES

doc/index.rst

@@ -13,6 +13,8 @@ on xarray objects.
    :maxdepth: 2
 
    examples/index
+   roadmap
+   contributing
 
 Indices and tables
 ==================

doc/roadmap.rst

@@ -0,0 +1,49 @@
+.. currentmodule:: cf_xarray
+
+Roadmap
+-------
+
+Goals
+=====
+
+1. Enable easy use of additional CF attributes that are not decoded by xarray.
+
+2. Provide a consolidated set of public helper functions that other packages can use to avoid
+   duplicated efforts in parsing CF attributes.
+
+Scope
+=====
+
+
+1. This package will not provide a full implementation of the CF data model using xarray objects.
+   This use case should be served by Iris.
+
+2. Unit support is left to ``pint-xarray`` and future xarray support for ``pint`` until it is clear
+   that there is a need for some functionality.
+
+3. Projections and CRS stuff is left to ``rioxarray`` and other geo-xarray packages. Some helper
+   functions could be folded in to ``cf-xarray`` to encourage consolidation in that sub-ecosystem.
+
+Design principles
+=================
+
+1. Be uncomplicated.
+
+   Avoid anything that requires saving state in accessor objects (for now).
+
+2. Be friendly.
+
+   Users should be allowed to mix CF names and variables names from the parent xarray object e.g.
+   ``ds.cf.plot(x="X", y="model_depth")``. This allows use with "imperfectly tagged" datasets.
+
+3. Be loud when wrapping to avoid confusion.
+
+   For e.g. the ``repr`` for ``cf.groupby("X")`` should make it clear that this is a
+   CF-wrapped ``Resample`` instance i.e. ``cf.groupby("X").mean("T")`` is allowed. Docstrings
+   should also clearly indicate wrapping by ``cf-xarray``; for e.g. ``ds.cf.isel``.
+
+4. Allow easy debugging and help build understanding.
+
+   Since ``cf_xarray`` depends on ``attrs`` being present and since ``attrs`` are easily lost in xarray
+   operations, we should allow easy diagnosis of what ``cf_xarray`` can decode for a particular
+   object.