docs fixes (#154)

Author: dcherian

cf_xarray/accessor.py

@@ -561,11 +561,6 @@ def _getitem(
     kind = str(type(obj).__name__)
     scalar_key = isinstance(key, str)
 
-    if isinstance(obj, DataArray) and not scalar_key:
-        raise KeyError(
-            f"Cannot use a list of keys with DataArrays. Expected a single string. Received {key!r} instead."
-        )
-
     if scalar_key:
         key = (key,)  # type: ignore
 
@@ -1172,9 +1167,6 @@ def get_associated_variable_names(self, name: Hashable) -> Dict[str, List[str]]:
 
         return coords
 
-    def __getitem__(self, key: Union[str, List[str]]):
-        return _getitem(self, key)
-
     def _maybe_to_dataset(self, obj=None) -> Dataset:
         if obj is None:
             obj = self._obj
@@ -1283,6 +1275,37 @@ def guess_coord_axis(self, verbose: bool = False) -> Union[DataArray, Dataset]:
 
 @xr.register_dataset_accessor("cf")
 class CFDatasetAccessor(CFAccessor):
+    def __getitem__(self, key: Union[str, List[str]]) -> Union[DataArray, Dataset]:
+        """
+        Index into a Dataset making use of CF attributes.
+
+        Parameters
+        ----------
+
+        key: str, Iterable[str], optional
+            One of
+              - axes names: "X", "Y", "Z", "T"
+              - coordinate names: "longitude", "latitude", "vertical", "time"
+              - cell measures: "area", "volume", or other names present in the \
+                             ``cell_measures`` attribute
+              - standard names: names present in ``standard_name`` attribute
+
+        Returns
+        -------
+        DataArray or Dataset
+          ``Dataset.cf[str]`` will return a DataArray, \
+          ``Dataset.cf[List[str]]``` will return a Dataset.
+
+        Notes
+        -----
+        In all cases, associated CF variables will be attached as coordinate variables
+        by parsing attributes such as ``bounds``, ``ancillary_variables``, etc.
+
+        ``bounds`` variables will not be attached when a DataArray is returned. This
+        is a limitation of the xarray data model.
+        """
+        return _getitem(self, key)
+
     def get_bounds(self, key: str) -> DataArray:
         """
         Get bounds variable corresponding to key.
@@ -1317,9 +1340,12 @@ def add_bounds(self, dims: Union[Hashable, Iterable[Hashable]]):
         -------
         DataArray or Dataset with bounds variables added and appropriate "bounds" attribute set.
 
+        Raises
+        ------
+        KeyError
+
         Notes
         -----
-
         The bounds variables are automatically named f"{dim}_bounds" where ``dim``
         is a dimension name.
         """
@@ -1511,4 +1537,41 @@ def decode_vertical_coords(self, prefix="z"):
 
 @xr.register_dataarray_accessor("cf")
 class CFDataArrayAccessor(CFAccessor):
+    def __getitem__(self, key: Union[str, List[str]]) -> DataArray:
+        """
+        Index into a DataArray making use of CF attributes.
+
+        Parameters
+        ----------
+        key: str, Iterable[str], optional
+            One of
+              - axes names: "X", "Y", "Z", "T"
+              - coordinate names: "longitude", "latitude", "vertical", "time"
+              - cell measures: "area", "volume", or other names present in the \
+                             ``cell_measures`` attribute
+              - standard names: names present in ``standard_name`` attribute of \
+                coordinate variables
+
+        Returns
+        -------
+        DataArray
+
+        Raises
+        ------
+        KeyError
+          ``DataArray.cf[List[str]]`` will raise KeyError.
+
+        Notes
+        -----
+        Associated CF variables will be attached as coordinate variables
+        by parsing attributes such as ``cell_measures``, ``coordinates`` etc.
+        """
+
+        if not isinstance(key, str):
+            raise KeyError(
+                f"Cannot use a list of keys with DataArrays. Expected a single string. Received {key!r} instead."
+            )
+
+        return _getitem(self, key)
+
     pass

cf_xarray/tests/datasets.py renamed to cf_xarray/datasets.py

@@ -9,8 +9,8 @@
 
 import cf_xarray  # noqa
 
+from ..datasets import airds, anc, ds_no_attrs, multiple, popds, romsds
 from . import raise_if_dask_computes
-from .datasets import airds, anc, ds_no_attrs, multiple, popds
 
 mpl.use("Agg")
 
@@ -586,7 +586,7 @@ def test_missing_variable_in_coordinates():
 
 
 def test_Z_vs_vertical_ROMS():
-    from .datasets import romsds
+    from ..datasets import romsds
 
     assert_identical(romsds.s_rho.reset_coords(drop=True), romsds.temp.cf["Z"])
     assert_identical(
@@ -612,8 +612,6 @@ def test_Z_vs_vertical_ROMS():
 
 
 def test_param_vcoord_ocean_s_coord():
-    from .datasets import romsds
-
     romsds.s_rho.attrs["standard_name"] = "ocean_s_coordinate_g2"
     Zo_rho = (romsds.hc * romsds.s_rho + romsds.Cs_r * romsds.h) / (
         romsds.hc + romsds.h

cf_xarray/tests/test_accessor.py

@@ -3,7 +3,7 @@
 
 import cf_xarray as cfxr  # noqa
 
-from .datasets import airds, mollwds
+from ..datasets import airds, mollwds
 
 try:
     from dask.array import Array as DaskArray

cf_xarray/tests/test_helpers.py

@@ -1,11 +1,28 @@
-.. currentmodule:: xarray
-
 API
 ===
 
+.. currentmodule:: cf_xarray
+
+Top-level API
+-------------
+
+.. autosummary::
+    :toctree: generated/
+
+    bounds_to_vertices
+    vertices_to_bounds
+
+
+.. currentmodule:: xarray
+
 DataArray
 ---------
 
+.. _daattr:
+
+Attributes
+~~~~~~~~~~
+
 .. autosummary::
    :toctree: generated/
    :template: autosummary/accessor_attribute.rst
@@ -16,6 +33,12 @@ DataArray
     DataArray.cf.standard_names
     DataArray.cf.plot
 
+
+.. _dameth:
+
+Methods
+~~~~~~~
+
 .. autosummary::
    :toctree: generated/
    :template: autosummary/accessor_method.rst
@@ -29,6 +52,11 @@ DataArray
 Dataset
 -------
 
+.. _dsattr:
+
+Attributes
+~~~~~~~~~~
+
 .. autosummary::
    :toctree: generated/
    :template: autosummary/accessor_attribute.rst
@@ -38,11 +66,16 @@ Dataset
     Dataset.cf.coordinates
     Dataset.cf.standard_names
 
+.. _dsmeth:
+
+Methods
+~~~~~~~
+
 .. autosummary::
    :toctree: generated/
    :template: autosummary/accessor_method.rst
 
-    DataArray.cf.__getitem__
+    Dataset.cf.__getitem__
     Dataset.cf.add_bounds
     Dataset.cf.bounds_to_vertices
     Dataset.cf.decode_vertical_coords
@@ -51,14 +84,3 @@ Dataset
     Dataset.cf.guess_coord_axis
     Dataset.cf.keys
     Dataset.cf.rename_like
-
-.. currentmodule:: cf_xarray
-
-Top-level API
--------------
-
-.. autosummary::
-    :toctree: generated/
-
-    bounds_to_vertices
-    vertices_to_bounds

doc/api.rst

@@ -1,5 +1,7 @@
 .. currentmodule:: xarray
 
+.. _criteria:
+
 CF Criteria
 -----------