Improve Dataset and DataArray docstrings (#4532)

* dataarray init docs to class

* dataset init docs to class doc

* Add a dataset example.

* Add an example to dataarray

* formatting

* formatting

* formatting

* formatting

* Remove imports, use dicts instead of dataarray

* remove imports, use dict() instead of {}, add attrs.

* add attrs

* typo

* print original dataset as well.

* print original dataarray as well

* Update whats-new.rst

* Move whatsnew to 0.16.2

* Update doc/whats-new.rst

* explicitly enable numpydoc and disable googledoc

* black

* Use isel instead of where.

* Use isel instead of where.

Co-authored-by: Maximilian Roos <[email protected]>
Co-authored-by: Maximilian Roos <[email protected]>
Co-authored-by: keewis <[email protected]>
Co-authored-by: Keewis <[email protected]>

Author: 3 people

doc/conf.py

@@ -111,6 +111,9 @@
 
 autodoc_typehints = "none"
 
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
 napoleon_use_param = False
 napoleon_use_rtype = True
 napoleon_preprocess_types = True

doc/whats-new.rst

@@ -62,8 +62,13 @@ Bug fixes
 Documentation
 ~~~~~~~~~~~~~
 
+- Update the docstring of :py:class:`DataArray` and :py:class:`Dataset`.
+  (:pull:`4532`);
+  By `Jimmy Westling <https://github.com/illviljan>`_.
 - Raise a more informative error when :py:meth:`DataArray.to_dataframe` is
-  is called on a scalar (:issue:`4228`). By `Pieter Gijsbers <https://github.com/pgijsbers>`_.
+  is called on a scalar, (:issue:`4228`); 
+  By `Pieter Gijsbers <https://github.com/pgijsbers>`_.
+
 
 Internal Changes
 ~~~~~~~~~~~~~~~~

xarray/core/dataarray.py

@@ -216,27 +216,125 @@ def __setitem__(self, key, value) -> None:
 class DataArray(AbstractArray, DataWithCoords):
     """N-dimensional array with labeled coordinates and dimensions.
 
-    DataArray provides a wrapper around numpy ndarrays that uses labeled
-    dimensions and coordinates to support metadata aware operations. The API is
-    similar to that for the pandas Series or DataFrame, but DataArray objects
-    can have any number of dimensions, and their contents have fixed data
-    types.
+    DataArray provides a wrapper around numpy ndarrays that uses
+    labeled dimensions and coordinates to support metadata aware
+    operations. The API is similar to that for the pandas Series or
+    DataFrame, but DataArray objects can have any number of dimensions,
+    and their contents have fixed data types.
 
     Additional features over raw numpy arrays:
 
     - Apply operations over dimensions by name: ``x.sum('time')``.
-    - Select or assign values by integer location (like numpy): ``x[:10]``
-      or by label (like pandas): ``x.loc['2014-01-01']`` or
+    - Select or assign values by integer location (like numpy):
+      ``x[:10]`` or by label (like pandas): ``x.loc['2014-01-01']`` or
       ``x.sel(time='2014-01-01')``.
-    - Mathematical operations (e.g., ``x - y``) vectorize across multiple
-      dimensions (known in numpy as "broadcasting") based on dimension names,
-      regardless of their original order.
-    - Keep track of arbitrary metadata in the form of a Python dictionary:
-      ``x.attrs``
+    - Mathematical operations (e.g., ``x - y``) vectorize across
+      multiple dimensions (known in numpy as "broadcasting") based on
+      dimension names, regardless of their original order.
+    - Keep track of arbitrary metadata in the form of a Python
+      dictionary: ``x.attrs``
     - Convert to a pandas Series: ``x.to_series()``.
 
-    Getting items from or doing mathematical operations with a DataArray
-    always returns another DataArray.
+    Getting items from or doing mathematical operations with a
+    DataArray always returns another DataArray.
+
+    Parameters
+    ----------
+    data : array_like
+        Values for this array. Must be an ``numpy.ndarray``, ndarray
+        like, or castable to an ``ndarray``. If a self-described xarray
+        or pandas object, attempts are made to use this array's
+        metadata to fill in other unspecified arguments. A view of the
+        array's data is used instead of a copy if possible.
+    coords : sequence or dict of array_like, optional
+        Coordinates (tick labels) to use for indexing along each
+        dimension. The following notations are accepted:
+
+        - mapping {dimension name: array-like}
+        - sequence of tuples that are valid arguments for
+          ``xarray.Variable()``
+          - (dims, data)
+          - (dims, data, attrs)
+          - (dims, data, attrs, encoding)
+
+        Additionally, it is possible to define a coord whose name
+        does not match the dimension name, or a coord based on multiple
+        dimensions, with one of the following notations:
+
+        - mapping {coord name: DataArray}
+        - mapping {coord name: Variable}
+        - mapping {coord name: (dimension name, array-like)}
+        - mapping {coord name: (tuple of dimension names, array-like)}
+
+    dims : hashable or sequence of hashable, optional
+        Name(s) of the data dimension(s). Must be either a hashable
+        (only for 1D data) or a sequence of hashables with length equal
+        to the number of dimensions. If this argument is omitted,
+        dimension names default to ``['dim_0', ... 'dim_n']``.
+    name : str or None, optional
+        Name of this array.
+    attrs : dict_like or None, optional
+        Attributes to assign to the new instance. By default, an empty
+        attribute dictionary is initialized.
+
+    Examples
+    --------
+    Create data:
+
+    >>> np.random.seed(0)
+    >>> temperature = 15 + 8 * np.random.randn(2, 2, 3)
+    >>> precipitation = 10 * np.random.rand(2, 2, 3)
+    >>> lon = [[-99.83, -99.32], [-99.79, -99.23]]
+    >>> lat = [[42.25, 42.21], [42.63, 42.59]]
+    >>> time = pd.date_range("2014-09-06", periods=3)
+    >>> reference_time = pd.Timestamp("2014-09-05")
+
+    Initialize a dataarray with multiple dimensions:
+
+    >>> da = xr.DataArray(
+    ...     data=temperature,
+    ...     dims=["x", "y", "time"],
+    ...     coords=dict(
+    ...         lon=(["x", "y"], lon),
+    ...         lat=(["x", "y"], lat),
+    ...         time=time,
+    ...         reference_time=reference_time,
+    ...     ),
+    ...     attrs=dict(
+    ...         description="Ambient temperature.",
+    ...         units="degC",
+    ...     ),
+    ... )
+    >>> da
+    <xarray.DataArray (x: 2, y: 2, time: 3)>
+    array([[[29.11241877, 18.20125767, 22.82990387],
+            [32.92714559, 29.94046392,  7.18177696]],
+    <BLANKLINE>
+           [[22.60070734, 13.78914233, 14.17424919],
+            [18.28478802, 16.15234857, 26.63418806]]])
+    Coordinates:
+        lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
+        lat             (x, y) float64 42.25 42.21 42.63 42.59
+      * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
+        reference_time  datetime64[ns] 2014-09-05
+    Dimensions without coordinates: x, y
+    Attributes:
+        description:  Ambient temperature.
+        units:        degC
+
+    Find out where the coldest temperature was:
+
+    >>> da.isel(da.argmin(...))
+    <xarray.DataArray ()>
+    array(7.18177696)
+    Coordinates:
+        lon             float64 -99.32
+        lat             float64 42.21
+        time            datetime64[ns] 2014-09-08
+        reference_time  datetime64[ns] 2014-09-05
+    Attributes:
+        description:  Ambient temperature.
+        units:        degC
     """
 
     _cache: Dict[str, Any]
@@ -274,45 +372,6 @@ def __init__(
         indexes: Dict[Hashable, pd.Index] = None,
         fastpath: bool = False,
     ):
-        """
-        Parameters
-        ----------
-        data : array_like
-            Values for this array. Must be an ``numpy.ndarray``, ndarray like,
-            or castable to an ``ndarray``. If a self-described xarray or pandas
-            object, attempts are made to use this array's metadata to fill in
-            other unspecified arguments. A view of the array's data is used
-            instead of a copy if possible.
-        coords : sequence or dict of array_like, optional
-            Coordinates (tick labels) to use for indexing along each dimension.
-            The following notations are accepted:
-
-            - mapping {dimension name: array-like}
-            - sequence of tuples that are valid arguments for xarray.Variable()
-              - (dims, data)
-              - (dims, data, attrs)
-              - (dims, data, attrs, encoding)
-
-            Additionally, it is possible to define a coord whose name
-            does not match the dimension name, or a coord based on multiple
-            dimensions, with one of the following notations:
-
-            - mapping {coord name: DataArray}
-            - mapping {coord name: Variable}
-            - mapping {coord name: (dimension name, array-like)}
-            - mapping {coord name: (tuple of dimension names, array-like)}
-
-        dims : hashable or sequence of hashable, optional
-            Name(s) of the data dimension(s). Must be either a hashable (only
-            for 1D data) or a sequence of hashables with length equal to the
-            number of dimensions. If this argument is omitted, dimension names
-            default to ``['dim_0', ... 'dim_n']``.
-        name : str or None, optional
-            Name of this array.
-        attrs : dict_like or None, optional
-            Attributes to assign to the new instance. By default, an empty
-            attribute dictionary is initialized.
-        """
         if fastpath:
             variable = data
             assert dims is None