improve docstrings with examples and links

This is a (incomplete) checklist for #5816 to make it easier to find methods that are in need of examples and links to the narrative docs with further information (of course, changes to the docstrings of all other methods / functions part of the public API are also appreciated).

Good examples explicitly construct small xarray objects to make it easier to follow (e.g. use np.{ones,full,zeros} or the np.array constructor instead of np.random / loading from files) and show both input and output of the function.

Use

pytest --doctest-modules xarray --ignore xarray/tests/

to verify the examples, or push to a PR to have the CI do it for you (note that you will have much quicker feedback locally though).

To link to other documentation pages we can use

:doc:`project:label`
    Description of the linked page

where we can leave out project if we link to somewhere within xarray’s documentation. To figure out the label, we can either look at the source, search the output of python -m sphinx.ext.intersphinx https://docs.xarray.dev/en/latest/objects.inv, or use sphobjinv (install from PyPI):

sphobjinv search -su https://docs.xarray.dev/en/latest/ missing

Top-level functions:

• get_options
• decode_cf
• polyval
• unify_chunks
• infer_freq
• date_range

I/O:

• load_dataarray
• load_dataset
• open_dataarray
• open_dataset
• open_mfdataset

Contents:

• DataArray.assign_attrs, Dataset.assign_attrs
• DataArray.expand_dims, Dataset.expand_dims
• DataArray.drop_duplicates, Dataset.drop_duplicates
• DataArray.drop_vars, Dataset.drop_vars
• Dataset.drop_dims
• DataArray.convert_calendar, Dataset.convert_calendar
• DataArray.set_coords, Dataset.set_coords
• DataArray.reset_coords, Dataset.reset_coords

Comparisons:

• DataArray.equals, Dataset.equals
• DataArray.identical, Dataset.identical
• DataArray.broadcast_equals, Dataset.broadcast_equals

Dask:

• DataArray.compute, Dataset.compute
• DataArray.chunk, Dataset.chunk
• DataArray.persist, Dataset.persist

Missing values:

• DataArray.bfill, Dataset.bfill
• DataArray.ffill, Dataset.ffill
• DataArray.fillna, Dataset.fillna
• DataArray.dropna, Dataset.dropna

Indexing:

• DataArray.drop_isel
• DataArray.drop_sel
• DataArray.head, Dataset.head
• DataArray.tail, Dataset.tail
• DataArray.interp_like, Dataset.interp_like
• DataArray.reindex_like, Dataset.reindex_like
• Dataset.isel

Aggregations:

• Dataset.argmax
• Dataset.argmin
• DataArray.cumsum, Dataset.cumsum (intermediate to advanced)
• DataArray.cumprod, Dataset.cumprod (intermediate to advanced)
• DataArray.reduce, Dataset.reduce

[keewis]

I thought I ran it on main, but apparently I made a mistake? You’re right, the aggregations and thin have examples now, but head and tail don’t

[DanielGoman]

I have added several docstring examples in #7123, but the CI fails on some checks that (to me) don’t seem related to the examples I added.

I’d appreciate if anybody could clarify this to me before I turn the draft to a PR 😃