documentation cleanup (#11179)

* don't document deprecated and removed pandas methods

* rst syntax error

* empty lines before lists or doctests

* pandas deprecation of a timedelta unit name

* restore a lot of the tags used by RTD

for reference, these mean:
* `-T`: show traceback
* `-W`: fail on warnings
* `--keep-going`: don't abort on the first warning
* `-j auto`: use as many processes as CPU cores available

* deduplicate `cubed-xarray` links

(not sure why this one fails but `pint-xarray` or `cupy-xarray` don't)

Author: keewis

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS      =
+SPHINXOPTS      = -T -W --keep-going -j auto
 SPHINXBUILD     = sphinx-build
 SPHINXATUOBUILD = sphinx-autobuild
 PAPER           =

doc/api-hidden.rst

@@ -421,7 +421,6 @@
    CFTimeIndex.factorize
    CFTimeIndex.fillna
    CFTimeIndex.floor
-   CFTimeIndex.format
    CFTimeIndex.get_indexer
    CFTimeIndex.get_indexer_for
    CFTimeIndex.get_indexer_non_unique
@@ -430,18 +429,10 @@
    CFTimeIndex.get_slice_bound
    CFTimeIndex.get_value
    CFTimeIndex.groupby
-   CFTimeIndex.holds_integer
    CFTimeIndex.identical
    CFTimeIndex.insert
    CFTimeIndex.intersection
    CFTimeIndex.is_
-   CFTimeIndex.is_boolean
-   CFTimeIndex.is_categorical
-   CFTimeIndex.is_floating
-   CFTimeIndex.is_integer
-   CFTimeIndex.is_interval
-   CFTimeIndex.is_numeric
-   CFTimeIndex.is_object
    CFTimeIndex.isin
    CFTimeIndex.isna
    CFTimeIndex.isnull
@@ -465,7 +456,6 @@
    CFTimeIndex.shift
    CFTimeIndex.slice_indexer
    CFTimeIndex.slice_locs
-   CFTimeIndex.sort
    CFTimeIndex.sort_values
    CFTimeIndex.sortlevel
    CFTimeIndex.strftime

doc/contribute/contributing.rst

@@ -245,6 +245,7 @@ You can either run pre-commit manually via Pixi as described above, or set up gi
 This is done by:
 
 .. code-block:: sh
+
     pixi shell -e pre-commit # enter the pre-commit environment
     pre-commit install # install the git hooks
 

doc/user-guide/duckarrays.rst

@@ -16,7 +16,7 @@ Some numpy-like array types that xarray already has some support for:
 * `Sparse <https://sparse.pydata.org/en/stable/>`_ - for performant arrays with many zero elements,
 * `Pint <https://pint.readthedocs.io/en/latest/>`_ - for tracking the physical units of your data (see `pint-xarray <https://pint-xarray.readthedocs.io>`_),
 * `Dask <https://docs.dask.org/en/stable/>`_ - parallel computing on larger-than-memory arrays (see :ref:`using dask with xarray <dask>`),
-* `Cubed <https://github.com/cubed-dev/cubed/tree/main/cubed>`_ - another parallel computing framework that emphasises reliability (see `cubed-xarray <https://github.com/cubed-dev/cubed-xarray>`_).
+* `Cubed <https://github.com/cubed-dev/cubed/tree/main/cubed>`_ - another parallel computing framework that emphasises reliability (see `cubed-xarray`_).
 
 .. warning::
 
@@ -231,4 +231,6 @@ easier. If you know of more that aren't on this list please raise an issue to ad
 
 - `pint-xarray <https://pint-xarray.readthedocs.io>`_
 - `cupy-xarray <https://cupy-xarray.readthedocs.io>`_
-- `cubed-xarray <https://github.com/cubed-xarray>`_
+- `cubed-xarray`_
+
+.. _cubed-xarray: https://github.com/cubed-dev/cubed-xarray

doc/user-guide/plotting.rst

@@ -212,7 +212,7 @@ from the time and assign it as a non-dimension coordinate:
 
 .. jupyter-execute::
 
-    decimal_day = (air1d.time - air1d.time[0]) / pd.Timedelta("1d")
+    decimal_day = (air1d.time - air1d.time[0]) / pd.Timedelta("1D")
     air1d_multi = air1d.assign_coords(decimal_day=("time", decimal_day.data))
     air1d_multi
 

xarray/computation/computation.py

@@ -696,6 +696,7 @@ def where(cond, x, y, keep_attrs=None):
     y : scalar, array, Variable, DataArray or Dataset
         values to choose from where `cond` is False
     keep_attrs : bool or {"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or callable, optional
+
         - 'override' or True (default): skip comparing and copy attrs from `x` to the result.
         - 'drop' or False: empty attrs on returned xarray object.
         - 'identical': all attrs must be the same on every object.
@@ -734,6 +735,7 @@ def where(cond, x, y, keep_attrs=None):
         standard_name:  sea_surface_temperature
 
     If `x` is a scalar then by default there are no attrs on the result
+
     >>> xr.where(x < 0.5, 1, 0)
     <xarray.DataArray 'sst' (lat: 10)> Size: 80B
     array([1, 1, 1, 1, 1, 0, 0, 0, 0, 0])
@@ -742,6 +744,7 @@ def where(cond, x, y, keep_attrs=None):
 
     If `x` is a scalar (and therefore has no attrs), preserve the
     attrs on `cond` by using `keep_attrs="drop_conflicts"`
+
     >>> xr.where(x < 0.5, 1, 0, keep_attrs="drop_conflicts")
     <xarray.DataArray 'sst' (lat: 10)> Size: 80B
     array([1, 1, 1, 1, 1, 0, 0, 0, 0, 0])