xarray
xarray copied to clipboard
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
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.
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
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?
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).
Excellent, I'll start working on it, thank you!
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 :)
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?
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
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!
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.