Allow wrapping .. deprecated:: directive in admonitions

[pvandyken]

I'd like the ability to wrap deprecation warnings within another sphinx admonition such as info or warning. My idea is to have an admonition argument in deprecated() which defaults to None but optionally takes the name of an admonition. The results would be as follows:

@deprecated(deprecated_in="1.0", details="This function is deprecated")
def my_func():
    """Docstring for the function"""

# leads to the following docstring:
"""Docstring for the function

.. deprecated::1.0
    This function is deprecated
"""

# versus
@deprecated(deprecated_in="1.0", details="This function is deprecated", admonition='warning')
def my_func():
    """Docstring for the function"""

# leads to the following docstring:
"""Docstring for the function

.. warning::
  .. deprecated::1.0
      This function is deprecated
"""

I already have clone with this implemented, the patch is very straightforward. If you agree to implement this I can make a PR.

Happy to change the name of the argument if you prefer as well.