Recommendations for domain-specific accessor documentation

[gmaze]

Hi,

I'm currently working on an ocean domain specific accessor for a machine learning technique (https://github.com/gmaze/pyxpcm/tree/nfeatures).
I implemented an xarray.DataSet accessor (name space pyxpcm) that I'd like to document.

I thus wonder whether the xarray/pangeo community has recommendations about how to do this appropriately ?

Right now, I simply have an API auto-generated page, see:
https://pyxpcm-dev.readthedocs.io/en/latest/api.html#xarray-dataset-accessor-the-pyxpcm-name-space

[jthielen]

@gmaze Just as an example, here is what we recently added for MetPy: https://unidata.github.io/MetPy/latest/api/generated/metpy.xarray.html. Previously, we just had a narrative-form tutorial.

If there are other recommendations, it would be great to incorporate those into MetPy as well!

[gmaze]

Thanks for the example @jthielen, this looks great !

May be it would be better to not show to readers the accessor class name, since it will never be seen on the API frontend, only the scope name will.

So it would be great to be able to have the documentation to read something like:

xarray.DataSet.<scope_name>.<accessor_method_or_property>

instead of:

<package_name>.xarray.<accessor_class_name>.<accessor_method_or_property>
(in the case where the accessor class is in xarray.py file on the package)

But I don't know how to manage that with sphinx documentation

[keewis]

comment from @benbovy in #3625:

I re-used pandas templates for xarray accessors here: https://github.com/benbovy/xarray-simlab/blob/45359e99cbf6341464b02cb937618c051a58a31c/doc/conf.py#L233

It works pretty well: https://xarray-simlab.readthedocs.io/en/latest/api.html#dataset-xsimlab-xarray-accessor

For reference, here's pandas' version: https://github.com/pandas-dev/pandas/blob/837daf18d480cce18c25844c591c39da19437252/doc/source/conf.py#L441-L591

I think to make this a bit easier for everyone we should add this to the documentation on accessors.

Also, we could create a sphinx extension module that contains all the code in conf.py so defining the custom directives would be as simple as adding something like "xarray.doc.accessors" to extensions. The module doesn't have to be in xarray, though, it could also become a separate package.

[benbovy]

I think to make this a bit easier for everyone we should add this to the documentation on accessors.

Agreed, this would definitely be useful.

Also, we could create a sphinx extension module that contains all the code in conf.py

I also agree! Since the code in conf.py is exactly the same for both pandas and xarray, it would be nice to hear thoughts from pandas developers @jorisvandenbossche.

[shoyer]

I think a documentation build only dependency would be very easy for both xarray and pandas to use. So a separate package (a sphinx extension?) sounds like a good idea.

[keewis]

I created such a package since I think I'm going to need that for pint-xarray. It currently lives at https://github.com/keewis/sphinx-autosummary-accessors