issue_comments

the issue is that we use functools.wraps to copy __doc__, __name__ and __qualname__ to newplotfunc. How about using ```python # Build on the original docstring dummy.doc = f"{plotfunc.doc}\n{commondoc}"

# to shorten the signature
@functools.wraps(plotfunc)
def dummy(darray, x, y, **kwargs):
     pass

# use the signature of dummy
del dummy.__wrapped__

@functools.wraps(dummy)
def newplotfunc(

``` instead of https://github.com/pydata/xarray/blob/1791c3b6f9852edca977c68c0bf52ed4406ef7b0/xarray/plot/plot.py#L572-L576

unfortunately, sphinx-autosummary-accessors can't fix all of this: some of the plotting functions have a signature of (x, y, z, ax, **kwargs). After passing through the autosummary / autodoc, this becomes (y, z, ax, **kwargs) (x was assumed to be self or darray). However, this doesn't match the documentation which claims to have darray, x, y and ax instead. Maybe we should try to fix that?

actually, it seems RTD unpinned the dependency versions (not sure when they did that) so we might even be able to make use of the hack. So: should we try using that package by installing from github, or would it be better to wait until there's a released version available?

I hacked around that issue in the PR so this issue would be fixed by switching to sphinx-autosummary-accessors. However, since RTD pins us to sphinx=1.8.5 (we can't change that when using conda) and the way the hack is written right now requires sphinx>=3.1, we won't be able to use it.

it seems fixing both the signature and the summary is a bit more involved than I thought and probably either requires changes to sphinx or partially rewriting the Autosummary class. Since using sphinx-autosummary-accessors will probably be the way to go here, let's continue that discussion in keewis/sphinx-autosummary-accessors#6