Standardize reporting known inconsistencies in dask.dataframe API

[avriiil]

Current situation
Portions of the dask.dataframe API are copied over directly from pandas using the @derived_from decorator. This pulls in the pandas docstring for the corresponding object and adds the "This docstring was copied from pandas. Some inconsistencies with the Dask version may exist."

Problem
New users often find the vagueness in this docstring confusing and intimidating -- Are there really inconsistencies? How many of them? What are they?

Proposed Situation

• Adopt a standardised method for reporting known inconsistencies. I've made a first attempt in Include known inconsistency in DataFrame str.split accessor docstring  #9177 - this format is very much open to discussion.
• Launch an organised effort to comb through the dask.dataframe API systematically to report known inconsistencies wherever possible. I'm not really sure what the best way to do this would be - perhaps a meta-issue or item in the overall Dask project board (if that exists?)

This process could be replicated for dask.array

[jrbourbeau]

Thanks @rrpelgrim. Optionally enumerating important discrepancies between pandas and Dask in auto-generated docstrings seems like a nice addition. We use the @derived_from decorator for automatically copying docstrings into Dask methods

dask/dask/utils.py

Line 774 in 068eb7f

def derived_from(original_klass, version=None, ua_args=None, skipblocks=0):

One option would be to add a new inconsistencies= keyword which takes a list of known discrepancies

@derived_from(
    pd.DataFrame,
    inconsistencies=["This is different", "this other thing is also different"],
)
def method(*args, **kwargs):
    ...

[avriiil]

@jrbourbeau -- I looked at this for a while today but can't quite figure out the correct location in the code where I should add the inconsistencies keyword.

Here's a draft PR that does not build correctly yet: #9192

Should it be added to the ignore_warnings function, the _derived_from helper or the derived_from function itself? Or all three?

[jrbourbeau]

I would add the new keyword to derived_from and forward it down through any necessary functions so it can be used with the "Some inconsistencies with the Dask version may exist" part of the docstring

[avriiil]

The inconsistencies keyword has been added here: #9192