Documentation for injected methods

[keewis]

At the moment, the documentation for methods introduced by accessors is broken. We work around this issue by directly referencing the corresponding accessor method or the underlying function. Of course, this is not how we recommend calling them, so we should try to fix this.

It seems this is mostly a sphinx issue since this is known (see #3333 and #3602), but we didn't find a way to resolve this. I'd like use this issue to collect ideas for solutions.

[keewis]

this kind of looks like it is related to or a duplicate of #3361.

I think pandas uses a system of autosummary templates for this. Maybe we can use something similar?

[keewis]

actually, we don't even need the templates. The issue is that property refuses to work correctly when called using the class (so ds.plot.scatter works but Dataset.plot.scatter raises an AttributeError). This means that as soon as we use a custom descriptor, documenting methods like Dataset.plot.scatter or Dataset.str.endswith should just work.

[benbovy]

I think pandas uses a system of autosummary templates for this. Maybe we can use something similar?

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

(Sorry I could have shared this sooner, I missed the issues here)

[keewis]

thanks, @benbovy, this really is useful. While we can generate documentation pages without the templates, the name on that page doesn't match the link.

I think we should add this to the docs (or make a helper module that others can import, or both) so this is a bit easier to find. Let's continue this discussion in #3361.