Silence sphinx warnings (#3516)

* silence sphinx warnings

* silence more sphinx warnings

* fix some references

* fix the docstrings of Dataset reduce methods

* mark the orphaned files as such

* silence some nit-picky warnings

* convert all references to xray to double backtick quoted text

* silence more warnings in whats-new.rst

* require a whatsnew format of Name <https://github.com/user>

* rename the second cf conventions link

* silence more sphinx warnings

* get interpolate_na docstrings in sync with master

* fix sphinx warnings for interpolate_na docstrings

* update references to old documentation sections

* cut the link to h5netcdf.File

* use the correct reference types for numpy

* update the reference to atop (dask renamed it to blockwise)

* rewrite numpy docstrings

* guard against non-str documentation

* pass name to skip_signature

* remove links to pandas.Panel

* convince sphinx to create pages astype and groupby().quantile

* more warnings

Author: keewis

doc/README.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 xarray
 ------
 

doc/api-hidden.rst

@@ -2,6 +2,8 @@
 .. This extra page is a work around for sphinx not having any support for
 .. hiding an autosummary table.
 
+:orphan:
+
 .. currentmodule:: xarray
 
 .. autosummary::
@@ -30,9 +32,11 @@
    core.groupby.DatasetGroupBy.first
    core.groupby.DatasetGroupBy.last
    core.groupby.DatasetGroupBy.fillna
+   core.groupby.DatasetGroupBy.quantile
    core.groupby.DatasetGroupBy.where
 
    Dataset.argsort
+   Dataset.astype
    Dataset.clip
    Dataset.conj
    Dataset.conjugate
@@ -71,6 +75,7 @@
    core.groupby.DataArrayGroupBy.first
    core.groupby.DataArrayGroupBy.last
    core.groupby.DataArrayGroupBy.fillna
+   core.groupby.DataArrayGroupBy.quantile
    core.groupby.DataArrayGroupBy.where
 
    DataArray.argsort

doc/combining.rst

@@ -255,11 +255,11 @@ Combining along multiple dimensions
   ``combine_nested``.
 
 For combining many objects along multiple dimensions xarray provides
-:py:func:`~xarray.combine_nested`` and :py:func:`~xarray.combine_by_coords`. These
+:py:func:`~xarray.combine_nested` and :py:func:`~xarray.combine_by_coords`. These
 functions use a combination of ``concat`` and ``merge`` across different
 variables to combine many objects into one.
 
-:py:func:`~xarray.combine_nested`` requires specifying the order in which the
+:py:func:`~xarray.combine_nested` requires specifying the order in which the
 objects should be combined, while :py:func:`~xarray.combine_by_coords` attempts to
 infer this ordering automatically from the coordinates in the data.
 
@@ -310,4 +310,4 @@ These functions can be used by :py:func:`~xarray.open_mfdataset` to open many
 files as one dataset. The particular function used is specified by setting the
 argument ``'combine'`` to ``'by_coords'`` or ``'nested'``. This is useful for
 situations where your data is split across many files in multiple locations,
-which have some known relationship between one another.
+which have some known relationship between one another.

doc/computation.rst

@@ -325,8 +325,8 @@ Broadcasting by dimension name
 ``DataArray`` objects are automatically align themselves ("broadcasting" in
 the numpy parlance) by dimension name instead of axis order. With xarray, you
 do not need to transpose arrays or insert dimensions of length 1 to get array
-operations to work, as commonly done in numpy with :py:func:`np.reshape` or
-:py:const:`np.newaxis`.
+operations to work, as commonly done in numpy with :py:func:`numpy.reshape` or
+:py:data:`numpy.newaxis`.
 
 This is best illustrated by a few examples. Consider two one-dimensional
 arrays with different sizes aligned along different dimensions:
@@ -566,7 +566,7 @@ to set ``axis=-1``. As an example, here is how we would wrap
 
 Because ``apply_ufunc`` follows a standard convention for ufuncs, it plays
 nicely with tools for building vectorized functions, like
-:func:`numpy.broadcast_arrays` and :func:`numpy.vectorize`. For high performance
+:py:func:`numpy.broadcast_arrays` and :py:class:`numpy.vectorize`. For high performance
 needs, consider using Numba's :doc:`vectorize and guvectorize <numba:user/vectorize>`.
 
 In addition to wrapping functions, ``apply_ufunc`` can automatically parallelize

doc/dask.rst

@@ -285,7 +285,7 @@ automate `embarrassingly parallel
 <https://en.wikipedia.org/wiki/Embarrassingly_parallel>`__ "map" type operations
 where a function written for processing NumPy arrays should be repeatedly
 applied to xarray objects containing Dask arrays. It works similarly to
-:py:func:`dask.array.map_blocks` and :py:func:`dask.array.atop`, but without
+:py:func:`dask.array.map_blocks` and :py:func:`dask.array.blockwise`, but without
 requiring an intermediate layer of abstraction.
 
 For the best performance when using Dask's multi-threaded scheduler, wrap a

doc/data-structures.rst

@@ -45,7 +45,7 @@ Creating a DataArray
 The :py:class:`~xarray.DataArray` constructor takes:
 
 - ``data``: a multi-dimensional array of values (e.g., a numpy ndarray,
-  :py:class:`~pandas.Series`, :py:class:`~pandas.DataFrame` or :py:class:`~pandas.Panel`)
+  :py:class:`~pandas.Series`, :py:class:`~pandas.DataFrame` or ``pandas.Panel``)
 - ``coords``: a list or dictionary of coordinates. If a list, it should be a
   list of tuples where the first element is the dimension name and the second
   element is the corresponding coordinate array_like object.
@@ -125,7 +125,7 @@ As a dictionary with coords across multiple dimensions:
 
 If you create a ``DataArray`` by supplying a pandas
 :py:class:`~pandas.Series`, :py:class:`~pandas.DataFrame` or
-:py:class:`~pandas.Panel`, any non-specified arguments in the
+``pandas.Panel``, any non-specified arguments in the
 ``DataArray`` constructor will be filled in from the pandas object:
 
 .. ipython:: python
@@ -301,7 +301,7 @@ names, and its data is aligned to any existing dimensions.
 
 You can also create an dataset from:
 
-- A :py:class:`pandas.DataFrame` or :py:class:`pandas.Panel` along its columns and items
+- A :py:class:`pandas.DataFrame` or ``pandas.Panel`` along its columns and items
   respectively, by passing it into the :py:class:`~xarray.Dataset` directly
 - A :py:class:`pandas.DataFrame` with :py:meth:`Dataset.from_dataframe <xarray.Dataset.from_dataframe>`,
   which will additionally handle MultiIndexes See :ref:`pandas`

doc/pandas.rst

@@ -112,7 +112,7 @@ automatically stacking them into a ``MultiIndex``.
 :py:meth:`DataArray.to_pandas() <xarray.DataArray.to_pandas>` is a shortcut that
 lets you convert a DataArray directly into a pandas object with the same
 dimensionality (i.e., a 1D array is converted to a :py:class:`~pandas.Series`,
-2D to :py:class:`~pandas.DataFrame` and 3D to :py:class:`~pandas.Panel`):
+2D to :py:class:`~pandas.DataFrame` and 3D to ``pandas.Panel``):
 
 .. ipython:: python