Include alternatives to deprecations in the documentation

StefRe · StefRe · commit 22005d73ce6a · 2021-12-22T16:43:09.000+01:00
- 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() &lt;.num2date&gt;`"
will create the directive

.. deprecated:: 3.5
   Use `num2date(e).timestamp() &lt;.num2date&gt;` 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."
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -326,6 +326,14 @@ Introducing
    All these helpers take a first parameter *since*, which should be set to
    the next point release, e.g. "3.x".
 
+   When providing alternatives in ``_api.warn_deprecated()`` or
+   ``@_api.deprecated``, you can use backticks to generate links to these
+   alternatives in the documentation. If the link differs from the caption to
+   be shown in the documentation, it can be added in angle brackets after a
+   space. Backticks including an optional leading dot are stripped from the
+   alternative and references are replaced by their caption (if any) when
+   emitting the deprecation warning.
+
 Expiring
 ~~~~~~~~
 
diff --git a/lib/matplotlib/_api/deprecation.py b/lib/matplotlib/_api/deprecation.py
@@ -14,6 +14,7 @@
 import functools
 import inspect
 import math
+import re
 import warnings
 
 
@@ -47,6 +48,8 @@ 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
+    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 +210,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
diff --git a/lib/matplotlib/tests/test_api.py b/lib/matplotlib/tests/test_api.py
@@ -85,3 +85,13 @@ def func(pre, arg, post=None):
         func(1, 2)
     with pytest.warns(_api.MatplotlibDeprecationWarning):
         func(1, 2, 3)
+
+
+def test_deprecation_alternative():
+    @_api.deprecated("1", alternative="`f1(arg) <.f1>` or `.f2` or `f3`")
+    def f():
+        pass
+    assert "`f1(arg) <.f1>` or `.f2` or `f3`" in f.__doc__
+    with pytest.warns(_api.MatplotlibDeprecationWarning,
+                      match=r".* f1\(arg\) or f2 or f3"):
+        f()
