def METHOD_NAME(reason=None, version=None, removed_in=None):
    """Decorate a function or class to designated it as deprecated.
    Will raise a `DeprecationWarning` when used and automatically adds a
    Sphinx '.. deprecated::' directive to the docstring.
    Parameters
    ----------
    reason : str, optional
        User-friendly reason for deprecating.
    version : str
        Version in which initially marked as deprecated.
    removed_in : str, optional
        Version in which the class or function will be removed.
    Returns
    -------
    decorator
    """
    if version is None:
        raise ValueError("version must be specified.")
    def decorator(func):
        @functools.wraps(func)
        def _wrapper(*args, **kwargs):
            warning = "%s is deprecated since version %s" % (func.__name__, version)
            if removed_in is not None:
                warning += " and will be removed in version %s." % removed_in
            else:
                warning += " and may be removed in a future version."
            if reason is not None:
                warning = warning + "  " + reason
            warnings.warn(warning, category=DeprecationWarning, stacklevel=2)
            return func(*args, **kwargs)
        # Generate Sphinx deprecated directive
        directive = ".. deprecated:: %s" % version
        if reason is not None:
            directive += "\n  %s" % reason
        try:
            functools.update_wrapper(_wrapper, func)
            # Insert directive into original docstring
            _wrapper.__doc__ = _insert_docstring_text(func, directive)
        except AttributeError:
            # __doc__ is not writable in Py27
            pass
        return _wrapper
    return decorator