improve docstrings with examples and links

[keewis]

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 easily generate the expected output install pytest-accept ([docs]()) in your dev environment and then run

pytest --doctest-modules FILE_NAME --accept || true

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.loc (no docstring at all - came up in https://github.com/pydata/xarray/discussions/7528#discussion-4858556)
• [ ] 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

[dcherian]

Thanks @keewis this is a great list

I guess you didn't run this on main?

The reductions all..var should have examples now. So do head tail and thin. the cumulative functions are injected so that may be too complex.

[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]

Hello :) I'm new to open source contribution. I'd like to work on this issue. As far as I understand, all there is to do is to add examples to the documentation and to verify the correctness of those examples. Am I correct?

[keewis]

yep, basically that, but linking to other sections in the documentation or related functions / methods is valuable as well (the "See Also" section).

Have a look at #7088 for a recent PR on this, although it's probably better to do one method at a time (it's up to you whether you want to work on the Dataset and DataArray version at the same time, though).

Don't hesitate to ask if you need help (either here, or in your PR).

[DanielGoman]

Excellent, I'll start working on it, thank you!

[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 :)

[Mehak-4545]

Hello @keewis! I'm Mehak, an Outreachy applicant from India in the July 2023 cohort. I would like to take up this issue and improve the documentation of some of the methods mentioned in the list. Can this issue be assigned to me?

[dcherian]

Hi @Mehak-4545 welcome to Xarray! Thank you for taking the time to contribute.

We don't assign issues usually. And this one is pretty comprehensive. Why don't you pick a few and comment here so that there are no overlapping efforts.

Please open a pull request and comment there if you have questions

[Mehak-4545]

Sure @dcherian, I shall do that. Thank you for responding! One concern I had regarding this is that when I click on "suggest edit" for documentation of a specific method on the xarray documentation, I am lead to the repo, but the path for those methods is not cantained in the repository. The issue can be seen in the screenshot attached. Is there some other procedure I have to follow to update the documentation? Thanks again!

[dcherian]

Thanks @Mehak-4545 . I think we need to fix that.

For now, you'll have to find the .py file for that method and edit the docstring manually. See #7669 for an example.