fix links in the documentation (#4686)

* convert the note directive to a numpydoc note section

* disable the use of rtype, with sphinx 3.3 the type will still be linked

* add back a lost author note

* don't reference the internal encode_cf_datetime function

* fix the links of a whats-new entry

* fix the docstrings of corr and cov

* remove all references to auto_combine

* link to rasterio's documentation using intersphinx

* fix the links to the Dataset or DataArray rolling or groupby methods

* reformat the return value docs for rolling

* fix the return value docs for coarsen

* link to dask.compute instead of dask.array.compute

Author: keewis

doc/conf.py

@@ -115,7 +115,7 @@
 napoleon_numpy_docstring = True
 
 napoleon_use_param = False
-napoleon_use_rtype = True
+napoleon_use_rtype = False
 napoleon_preprocess_types = True
 napoleon_type_aliases = {
     # general terms
@@ -418,6 +418,7 @@
     "matplotlib": ("https://matplotlib.org", None),
     "dask": ("https://docs.dask.org/en/latest", None),
     "cftime": ("https://unidata.github.io/cftime", None),
+    "rasterio": ("https://rasterio.readthedocs.io/en/latest", None),
     "sparse": ("https://sparse.pydata.org/en/latest/", None),
 }
 

doc/whats-new.rst

@@ -115,7 +115,7 @@ Bug fixes
 ~~~~~~~~~
 
 - Fix bug where reference times without padded years (e.g. ``since 1-1-1``) would lose their units when
-  being passed by :py:func:`encode_cf_datetime` (:issue:`4422`, :pull:`4506`). Such units are ambiguous
+  being passed by ``encode_cf_datetime`` (:issue:`4422`, :pull:`4506`). Such units are ambiguous
   about which digit represents the years (is it YMD or DMY?). Now, if such formatting is encountered,
   it is assumed that the first digit is the years, they are padded appropriately (to e.g. ``since 0001-1-1``)
   and a warning that this assumption is being made is issued. Previously, without ``cftime``, such times
@@ -319,8 +319,10 @@ Internal Changes
 
   All are up from 6 months (:issue:`4295`)
   `Guido Imperiale <https://github.com/crusaderky>`_.
-- Use :py:func:`dask.array.apply_gufunc` instead of :py:func:`dask.array.blockwise` in
-  :py:func:`xarray.apply_ufunc` when using ``dask='parallelized'``. (:pull:`4060`, :pull:`4391`, :pull:`4392`)
+- Use :py:func:`dask.array.apply_gufunc <dask.array.gufunc.apply_gufunc>` instead of
+  :py:func:`dask.array.blockwise` in :py:func:`xarray.apply_ufunc` when using
+  ``dask='parallelized'``. (:pull:`4060`, :pull:`4391`, :pull:`4392`)
+  By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
 - Align ``mypy`` versions to ``0.782`` across ``requirements`` and
   ``.pre-commit-config.yml`` files. (:pull:`4390`)
   By `Maximilian Roos <https://github.com/max-sixty>`_

xarray/core/combine.py

@@ -518,7 +518,6 @@ def combine_nested(
     --------
     concat
     merge
-    auto_combine
     """
     if isinstance(concat_dim, (str, DataArray)) or concat_dim is None:
         concat_dim = [concat_dim]

xarray/core/common.py

@@ -817,8 +817,9 @@ def rolling(
 
         Returns
         -------
-        Rolling object (core.rolling.DataArrayRolling for DataArray,
-        core.rolling.DatasetRolling for Dataset.)
+        core.rolling.DataArrayRolling or core.rolling.DatasetRolling
+            A rolling object (``DataArrayRolling`` for ``DataArray``,
+            ``DatasetRolling`` for ``Dataset``)
 
         Examples
         --------
@@ -929,8 +930,9 @@ def coarsen(
 
         Returns
         -------
-        Coarsen object (core.rolling.DataArrayCoarsen for DataArray,
-        core.rolling.DatasetCoarsen for Dataset.)
+        core.rolling.DataArrayCoarsen or core.rolling.DatasetCoarsen
+            A coarsen object (``DataArrayCoarsen`` for ``DataArray``,
+            ``DatasetCoarsen`` for ``Dataset``)
 
         Examples
         --------

xarray/core/computation.py

@@ -1148,24 +1148,24 @@ def cov(da_a, da_b, dim=None, ddof=1):
 
     Parameters
     ----------
-    da_a: DataArray
+    da_a : DataArray
         Array to compute.
-    da_b: DataArray
+    da_b : DataArray
         Array to compute.
     dim : str, optional
         The dimension along which the covariance will be computed
-    ddof: int, optional
+    ddof : int, optional
         If ddof=1, covariance is normalized by N-1, giving an unbiased estimate,
         else normalization is by N.
 
     Returns
     -------
-    covariance: DataArray
+    covariance : DataArray
 
     See also
     --------
-    pandas.Series.cov: corresponding pandas function
-    xr.corr: respective function to calculate correlation
+    pandas.Series.cov : corresponding pandas function
+    xarray.corr: respective function to calculate correlation
 
     Examples
     --------
@@ -1229,11 +1229,11 @@ def corr(da_a, da_b, dim=None):
 
     Parameters
     ----------
-    da_a: DataArray
+    da_a : DataArray
         Array to compute.
-    da_b: DataArray
+    da_b : DataArray
         Array to compute.
-    dim: str, optional
+    dim : str, optional
         The dimension along which the correlation will be computed
 
     Returns
@@ -1242,8 +1242,8 @@ def corr(da_a, da_b, dim=None):
 
     See also
     --------
-    pandas.Series.corr: corresponding pandas function
-    xr.cov: underlying covariance function
+    pandas.Series.corr : corresponding pandas function
+    xarray.cov : underlying covariance function
 
     Examples
     --------

xarray/core/concat.py

@@ -160,7 +160,6 @@ def concat(
     See also
     --------
     merge
-    auto_combine
 
     Examples
     --------

xarray/core/dataarray.py

@@ -856,11 +856,11 @@ def load(self, **kwargs) -> "DataArray":
         Parameters
         ----------
         **kwargs : dict
-            Additional keyword arguments passed on to ``dask.array.compute``.
+            Additional keyword arguments passed on to ``dask.compute``.
 
         See Also
         --------
-        dask.array.compute
+        dask.compute
         """
         ds = self._to_temp_dataset().load(**kwargs)
         new = self._from_temp_dataset(ds)
@@ -881,11 +881,11 @@ def compute(self, **kwargs) -> "DataArray":
         Parameters
         ----------
         **kwargs : dict
-            Additional keyword arguments passed on to ``dask.array.compute``.
+            Additional keyword arguments passed on to ``dask.compute``.
 
         See Also
         --------
-        dask.array.compute
+        dask.compute
         """
         new = self.copy(deep=False)
         return new.load(**kwargs)
@@ -2994,10 +2994,10 @@ def diff(self, dim: Hashable, n: int = 1, label: Hashable = "upper") -> "DataArr
         difference : same type as caller
             The n-th order finite difference of this object.
 
-        .. note::
-
-            `n` matches numpy's behavior and is different from pandas' first
-            argument named `periods`.
+        Notes
+        -----
+        `n` matches numpy's behavior and is different from pandas' first argument named
+        `periods`.
 
 
         Examples

xarray/core/dataset.py

@@ -779,11 +779,11 @@ def load(self, **kwargs) -> "Dataset":
         Parameters
         ----------
         **kwargs : dict
-            Additional keyword arguments passed on to ``dask.array.compute``.
+            Additional keyword arguments passed on to ``dask.compute``.
 
         See Also
         --------
-        dask.array.compute
+        dask.compute
         """
         # access .data to coerce everything to numpy or dask arrays
         lazy_data = {
@@ -951,11 +951,11 @@ def compute(self, **kwargs) -> "Dataset":
         Parameters
         ----------
         **kwargs : dict
-            Additional keyword arguments passed on to ``dask.array.compute``.
+            Additional keyword arguments passed on to ``dask.compute``.
 
         See Also
         --------
-        dask.array.compute
+        dask.compute
         """
         new = self.copy(deep=False)
         return new.load(**kwargs)

xarray/core/rolling.py

@@ -41,10 +41,10 @@ class Rolling:
 
     See Also
     --------
-    Dataset.groupby
-    DataArray.groupby
-    Dataset.rolling
-    DataArray.rolling
+    xarray.Dataset.groupby
+    xarray.DataArray.groupby
+    xarray.Dataset.rolling
+    xarray.DataArray.rolling
     """
 
     __slots__ = ("obj", "window", "min_periods", "center", "dim", "keep_attrs")
@@ -209,10 +209,10 @@ def __init__(self, obj, windows, min_periods=None, center=False, keep_attrs=None
 
         See Also
         --------
-        DataArray.rolling
-        DataArray.groupby
-        Dataset.rolling
-        Dataset.groupby
+        xarray.DataArray.rolling
+        xarray.DataArray.groupby
+        xarray.Dataset.rolling
+        xarray.Dataset.groupby
         """
         super().__init__(
             obj, windows, min_periods=min_periods, center=center, keep_attrs=keep_attrs
@@ -526,10 +526,10 @@ def __init__(self, obj, windows, min_periods=None, center=False, keep_attrs=None
 
         See Also
         --------
-        Dataset.rolling
-        DataArray.rolling
-        Dataset.groupby
-        DataArray.groupby
+        xarray.Dataset.rolling
+        xarray.DataArray.rolling
+        xarray.Dataset.groupby
+        xarray.DataArray.groupby
         """
         super().__init__(obj, windows, min_periods, center, keep_attrs)
         if any(d not in self.obj.dims for d in self.dim):