Rewrite docstrings

Currently we blindly copy dask.array and dask.dataframe docstrings from NumPy and Pandas. This allows us to avoid rewriting hundreds of docstrings.

However, this fails when the dask operation and the numpy/pandas operation differ slightly, as often occurs when we support only a subset of functionality. This appears to be confusing users who inspect our documentation, try something out, and then receive an error when it doesn’t work (see this example).

There are some efforts to mitigate this, for example derived_from takes a list of unavailable arguments to add to the docstring. However this keyword argument is virtually unused.

Some solutions

1. Crowd-sourced effort to rewrite docstrings manually
2. Add disclaimer to all wrapped functions that it is merely a copy
3. ?

[soloz]

Hi,

I’ve been using dask - thanks for the work. So its time to start giving back. For start, I’m happy to work on this, #1592 and #1606 and see how I get on with. Also happy to sync with anyone already doing so.

Should put in a pr over the coming days.

[TomAugspurger]

Talking with @jsignell, we may want to just strip out parameters that aren’t supported by dask.

Rather than

Parameters
----------
rule : DateOffset, Timedelta or str
    The offset string or object representing target conversion.
axis : {0 or 'index', 1 or 'columns'}, default 0  (Not supported in Dask)
    Which axis to use for up- or down-sampling. For `Series` this
    will default to 0, i.e. along the rows. Must be
    `DatetimeIndex`, `TimedeltaIndex` or `PeriodIndex`.
closed : {'right', 'left'}, default None
...

We’d have

Parameters
----------
rule : DateOffset, Timedelta or str
    The offset string or object representing target conversion.
closed : {'right', 'left'}, default None
...

Notes
------
The following paramerts are not supported by dask

* axis
* ...

or put that next to the dask disclaimer.