Repository navigation
improve docstrings with examples and links #6793
Description
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 pagewhere 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/ missingTop-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 Why how is [] different from loc[] ? #7528 (comment)) -
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(intermediate to advanced) -
Dataset.cumsum(intermediate to advanced) -
DataArray.cumprod(intermediate to advanced) -
Dataset.cumprod(intermediate to advanced) -
DataArray.reduce -
Dataset.reduce
Activity
[-]missing examples in docstrings[/-][+]improve docstrings with examples and links[/+]dcherian commentedon Jul 16, 2022
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 commentedon Jul 16, 2022
I thought I ran it on
main, but apparently I made a mistake? You're right, the aggregations andthinhave examples now, butheadandtaildon'tDanielGoman commentedon Oct 3, 2022
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 commentedon Oct 3, 2022
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
DatasetandDataArrayversion at the same time, though).Don't hesitate to ask if you need help (either here, or in your PR).
DanielGoman commentedon Oct 3, 2022
Excellent, I'll start working on it, thank you!
DanielGoman commentedon Oct 12, 2022
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 commentedon Mar 22, 2023
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 commentedon Mar 22, 2023
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 commentedon Mar 22, 2023
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 commentedon Mar 24, 2023
Thanks @Mehak-4545 . I think we need to fix that.
For now, you'll have to find the
.pyfile for that method and edit the docstring manually. See #7669 for an example.DOC add tested Dataset.drop_duplicates examples (pydataGH-6793)
DOC: Add examples for Dataset.drop_duplicates (#11713)
Add the remaining docstring examples from #6793 (#11827)