Remove 'out' from docstrings for wrapped numpy unary functions

[dcherian]

• Closes can't do in-place clip() with DataArrays. #1997

Inserting the string "The out keyword argument is not supported" is hacky. Can we do without that and just remove out=None from the signature?

[fmaussion]

Thanks!

I wonder is this is the best way to do this but I don't have a better idea either. Surely @shoyer can weight in.

Anyways, this doesn't pass through the tests because sometimes __doc__ is None. Also I think we need some kind of test for this.

[dcherian]

Ugh, serves me right for submitting PRs late at night. Thanks, @fmaussion. I'll wait for feedback on the approach before fixing it.

[shoyer]

The cleaner solution here would be to try to get rid of _method_wrapper by writing explicit methods/functions implemented with apply_ufunc:

xarray/xarray/core/ops.py

Lines 34 to 40 in a525405

	# methods which pass on the numpy return value unchanged
	# be careful not to list methods that we would want to wrap later
	NUMPY_SAME_METHODS = ['item', 'searchsorted']
	# methods which don't modify the data shape, so the result should still be
	# wrapped in an Variable/DataArray
	NUMPY_UNARY_METHODS = ['astype', 'argsort', 'clip', 'conj', 'conjugate']
	PANDAS_UNARY_FUNCTIONS = ['isnull', 'notnull']

This is the strategy suggested in this TODO note:

xarray/xarray/core/ops.py

Lines 3 to 5 in a525405

	TODO(shoyer): rewrite this module, making use of xarray.core.computation,
	NumPy's __array_ufunc__ and mixin classes instead of the unintuitive "inject"
	functions.

This is a bit more verbose but it would be much more obvious what's going on.

clip would probably be the place to start, since it's the only one with an invalid out argument. You could just copy the relevant parts of the docstring from NumPy.

[dcherian]

OK It'll take me some time to get to that. Closing.