issues: 603930174

This data as json

id node_id number title user state locked assignee milestone comments created_at updated_at closed_at author_association active_lock_reason draft pull_request body reactions performed_via_github_app state_reason repo type
603930174 MDExOlB1bGxSZXF1ZXN0NDA2NjE5MDkz 3988 built-in accessor documentation 14808389 closed 0     7 2020-04-21T11:39:36Z 2020-06-13T17:52:51Z 2020-06-13T17:52:46Z MEMBER   0 pydata/xarray/pulls/3988

We currently use property to attach our built-in accessors (plot, dt and str) to the DataArray and Dataset classes. However, because property returns itself when trying to access it as a class attribute, this does not work when generating the documentation (sphinx inspects classes, not class instances).

This adds a property-like descriptor that works on both classes and instance objects (the name could be more descriptive) and uses that to document the Dataset.plot.* and DataArray.plot.* methods (see the rendered documentation). I have not been able to get sphinx to work with _PlotMethods.__slots__, though.

A few questions / comments on this: 1. I noticed we have DataArray.plot.__call__ and xarray.plot.plot but not DataArray.plot.plot. Is that something that is worth adding?

  1. The functions decorated with the custom property define docstrings which currently are lost. Should we patch them on their return values?

  2. Right now, the error message when accidentally trying to call e.g. xr.DataArray.plot.line() is not very helpful: pytb AttributeError: 'NoneType' object has no attribute 'dims'

  3. Now that we can document the accessors, we need to think about how to structure api.rst. For plot and str, we could just list methods / attributes in subsections of DataArray / Dataset (or keep the Plotting / str / ... sections and add class subsections?), but dt is more complicated since it dispatches for datetime and timedelta

  4. [x] Closes #3625

  5. [x] Passes isort -rc . && black . && mypy . && flake8
  6. [x] Fully documented, including whats-new.rst for all changes and api.rst for new API

Edit: err, it seems I used the branch I pushed to the main repository for a documentation preview for this...

 
{
    "url": "https://api.github.com/repos/pydata/xarray/issues/3988/reactions",
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
     13221727 pull

Links from other tables