Include alternatives to deprecations in the documentation

- add `alternative` and `addendum` to the documentation by including
  them in the second argument of the `.. deprecated::` directive
- allow for backticks and optional reference to create links to the
  mentioned alternatives in the documentation
- remove these additional links and backticks in the deprecation
  warning message that is emitted when using a deprecated item

Example:
@_api.deprecated("3.5", alternative="`num2date(e).timestamp()<.num2date>`"
will create the directive

.. deprecated:: 3.5
   Use `num2date(e).timestamp()<.num2date>` instead.

which creates a link to matplotlib.dates.num2date with the caption
num2date(e).timestamp(). The deprecation warning message will read
"... Use num2date(e).timestamp() instead."

Author: StefRe

doc/devel/contributing.rst

@@ -326,6 +326,10 @@ Introducing
    All these helpers take a first parameter *since*, which should be set to
    the next point release, e.g. "3.x".
 
+   You can use standard rst cross references in the alternative. The string
+   will be processed to remove back ticks and only include the link caption
+   in the runtime warning.
+
 Expiring
 ~~~~~~~~
 

lib/matplotlib/_api/deprecation.py

@@ -14,6 +14,7 @@
 import functools
 import inspect
 import math
+import re
 import warnings
 
 
@@ -47,6 +48,10 @@ def _generate_deprecation_warning(
             + (" %(addendum)s" if addendum else ""))
     warning_cls = (PendingDeprecationWarning if pending
                    else MatplotlibDeprecationWarning)
+    # remove backticks, optional leading dot and replace reference by caption
+    if alternative:
+        alternative = re.sub(r"`([^`]*?) *<.*?>`|`\.?(.+?)`", r"\1\2",
+                             alternative)
     return warning_cls(message % dict(
         func=name, name=name, obj_type=obj_type, since=since, removal=removal,
         alternative=alternative, addendum=addendum))
@@ -207,10 +212,13 @@ def wrapper(*args, **kwargs):
         old_doc = inspect.cleandoc(old_doc or '').strip('\n')
 
         notes_header = '\nNotes\n-----'
+        second_arg = ' '.join([t.strip() for t in
+                               (message, f"Use {alternative} instead."
+                                if alternative else "", addendum) if t])
         new_doc = (f"[*Deprecated*] {old_doc}\n"
                    f"{notes_header if notes_header not in old_doc else ''}\n"
                    f".. deprecated:: {since}\n"
-                   f"   {message.strip()}")
+                   f"   {second_arg}")
 
         if not old_doc:
             # This is to prevent a spurious 'unexpected unindent' warning from

lib/matplotlib/tests/test_api.py

@@ -85,3 +85,14 @@ def func(pre, arg, post=None):
         func(1, 2)
     with pytest.warns(_api.MatplotlibDeprecationWarning):
         func(1, 2, 3)
+
+
+def test_deprecation_alternative():
+    alternative = "`.f1`, `f2`, `f3(x) <.f3>` or `f4(x)<f4>`"
+    @_api.deprecated("1", alternative=alternative)
+    def f():
+        pass
+    assert alternative in f.__doc__
+    with pytest.warns(_api.MatplotlibDeprecationWarning,
+                      match=r".* f1, f2, f3\(x\) or f4\(x\)"):
+        f()