DOC: Autoreformat all docstrings. (#5122)

Surprisingly not many changes, most of them are adding leading */** to
args, kwargs which is not clear according to numpydoc but seem like the
thigs to do, plus it's already done in a few other places.

A couple of spaces before `:`, that semantically matter. Numpydoc
improperly parse the types if there is no space before the :,
a documented parameter that does not exist on the function, and
some casing of section names.

There are a couple errors that this was not able to autofix (like
missing blank line before `Returns` section leading Numpydoc to
inpterprete "Returns" as a parameter of the function in
   xarray/core/dataset.py:roll  extra parameters: {'-------', 'rolled', 'Returns'}

Author: Carreau

xarray/core/common.py

@@ -490,9 +490,9 @@ def assign_attrs(self, *args, **kwargs):
 
         Parameters
         ----------
-        args
+        *args
             positional arguments passed into ``attrs.update``.
-        kwargs
+        **kwargs
             keyword arguments passed into ``attrs.update``.
 
         Returns
@@ -527,9 +527,9 @@ def pipe(
             Alternatively a ``(callable, data_keyword)`` tuple where
             ``data_keyword`` is a string indicating the keyword of
             ``callable`` that expects the xarray object.
-        args
+        *args
             positional arguments passed into ``func``.
-        kwargs
+        **kwargs
             a dictionary of keyword arguments passed into ``func``.
 
         Returns

xarray/core/computation.py

@@ -1355,7 +1355,7 @@ def dot(*arrays, dims=None, **kwargs):
 
     Parameters
     ----------
-    arrays : DataArray or Variable
+    *arrays : DataArray or Variable
         Arrays to compute.
     dims : ..., str or tuple of str, optional
         Which dimensions to sum over. Ellipsis ('...') sums over all dimensions.

xarray/core/dask_array_compat.py

@@ -105,9 +105,9 @@ def ensure_minimum_chunksize(size, chunks):
 
         Parameters
         ----------
-        size: int
+        size : int
             The maximum size of any chunk.
-        chunks: tuple
+        chunks : tuple
             Chunks along one axis, e.g. ``(3, 3, 2)``
 
         Examples

xarray/core/dataarray.py

@@ -2131,9 +2131,6 @@ def to_unstacked_dataset(self, dim, level=0):
         level : int or str
             The MultiIndex level to expand to a dataset along. Can either be
             the integer index of the level or its name.
-        label : int, default: 0
-            Label of the level to expand dataset along. Overrides the label
-            argument if given.
 
         Returns
         -------
@@ -2455,7 +2452,7 @@ def interpolate_na(
             If True, the dataarray's attributes (`attrs`) will be copied from
             the original object to the new one.  If False, the new
             object will be returned without attributes.
-        kwargs : dict, optional
+        **kwargs : dict, optional
             parameters passed verbatim to the underlying interpolation function
 
         Returns
@@ -4379,7 +4376,7 @@ def query(
             The default of 'pandas' parses code slightly different than standard
             Python. Alternatively, you can parse an expression using the 'python'
             parser to retain strict Python semantics.
-        engine: {"python", "numexpr", None}, default: None
+        engine : {"python", "numexpr", None}, default: None
             The engine used to evaluate the expression. Supported engines are:
             - None: tries to use numexpr, falls back to python
             - "numexpr": evaluates expressions using numexpr
@@ -4462,7 +4459,7 @@ def curvefit(
             Optional dictionary of parameter names to bounding values passed to the
             `curve_fit` `bounds` arg. If none or only some parameters are passed, the rest
             will be unbounded following the default scipy behavior.
-        param_names: seq, optional
+        param_names : seq, optional
             Sequence of names for the fittable parameters of `func`. If not supplied,
             this will be automatically determined by arguments of `func`. `param_names`
             should be manually supplied when fitting a function that takes a variable
@@ -4480,7 +4477,7 @@ def curvefit(
             [var]_curvefit_covariance
                 The covariance matrix of the coefficient estimates.
 
-        See also
+        See Also
         --------
         DataArray.polyfit
         scipy.optimize.curve_fit

xarray/core/dataset.py

@@ -4568,7 +4568,7 @@ def interpolate_na(
                   * x        (x) int64 0 1 2 3 4 5 6 7 8
 
             The gap lengths are 3-0 = 3; 6-3 = 3; and 8-6 = 2 respectively
-        kwargs : dict, optional
+        **kwargs : dict, optional
             parameters passed verbatim to the underlying interpolation function
 
         Returns
@@ -7087,7 +7087,7 @@ def query(
             The default of 'pandas' parses code slightly different than standard
             Python. Alternatively, you can parse an expression using the 'python'
             parser to retain strict Python semantics.
-        engine: {"python", "numexpr", None}, default: None
+        engine : {"python", "numexpr", None}, default: None
             The engine used to evaluate the expression. Supported engines are:
             - None: tries to use numexpr, falls back to python
             - "numexpr": evaluates expressions using numexpr
@@ -7178,7 +7178,7 @@ def curvefit(
             Optional dictionary of parameter names to bounding values passed to the
             `curve_fit` `bounds` arg. If none or only some parameters are passed, the rest
             will be unbounded following the default scipy behavior.
-        param_names: seq, optional
+        param_names : seq, optional
             Sequence of names for the fittable parameters of `func`. If not supplied,
             this will be automatically determined by arguments of `func`. `param_names`
             should be manually supplied when fitting a function that takes a variable
@@ -7196,7 +7196,7 @@ def curvefit(
             [var]_curvefit_covariance
                 The covariance matrix of the coefficient estimates.
 
-        See also
+        See Also
         --------
         Dataset.polyfit
         scipy.optimize.curve_fit

xarray/plot/facetgrid.py

@@ -238,7 +238,7 @@ def map_dataarray(self, func, x, y, **kwargs):
             plotting method such as `xarray.plot.imshow`
         x, y : string
             Names of the coordinates to plot on x, y axes
-        kwargs
+        **kwargs
             additional keyword arguments to func
 
         Returns
@@ -507,7 +507,7 @@ def set_titles(self, template="{coord} = {value}", maxchar=30, size=None, **kwar
             Template for plot titles containing {coord} and {value}
         maxchar : int
             Truncate titles at maxchar
-        kwargs : keyword args
+        **kwargs : keyword args
             additional arguments to matplotlib.text
 
         Returns
@@ -603,11 +603,11 @@ def map(self, func, *args, **kwargs):
             must plot to the currently active matplotlib Axes and take a
             `color` keyword argument. If faceting on the `hue` dimension,
             it must also take a `label` keyword argument.
-        args : strings
+        *args : strings
             Column names in self.data that identify variables with data to
             plot. The data for each variable is passed to `func` in the
             order the variables are specified in the call.
-        kwargs : keyword arguments
+        **kwargs : keyword arguments
             All keyword arguments are passed to the plotting function.
 
         Returns

xarray/tutorial.py

@@ -62,7 +62,7 @@ def open_dataset(
         The directory in which to search for and write cached data.
     cache : bool, optional
         If True, then cache data locally for use on subsequent calls
-    kws : dict, optional
+    **kws : dict, optional
         Passed to xarray.open_dataset
 
     Notes