Deprecate \stackrel.

Mathtext's \stackrel{a}{b} behaves subtly differently from latex's
\stackrel{a}{b}: mathtext makes `a` and `b` equal-sized whereas latex
makes `a` smaller than `b` (`a` is an "annotation" over `b`).  Given
that we can already stack expressions using the (admittedly less
practical, but standard) \genfrac, just deprecate \stackrel instead of
maintaining our own latex-like dialect.

Also undeprecate passing obj_type to the cbook.deprecated decorator(!),
given that this PR has a good reason to use it... and while we're at it,
reorder the kwargs docs for cbook.deprecated and cbook.warn_deprecated
to match the order in the signature.

doc/api/next_api_changes/2018-08-19-AL-deprecations.rst

@@ -0,0 +1,11 @@
+Deprecations
+````````````
+
+The ``\stackrel`` mathtext command is deprecated (it behaved differently
+from LaTeX's ``\stackrel``.  To stack two mathtext expressions, use
+``\genfrac{left-delim}{right-delim}{fraction-bar-thickness}{}{top}{bottom}``.
+
+Undeprecations
+``````````````
+
+The ``obj_type`` kwarg to the ``cbook.deprecated`` decorator is undeprecated.

examples/text_labels_and_annotations/mathtext_examples.py

@@ -34,7 +34,7 @@
     r"\alpha_{i+1}^j = {\rm sin}(2\pi f_j t_i) e^{-5 t_i/\tau},\ "
     r"\ldots$",
 
-    2: r"$\frac{3}{4},\ \binom{3}{4},\ \stackrel{3}{4},\ "
+    2: r"$\frac{3}{4},\ \binom{3}{4},\ \genfrac{}{}{0}{}{3}{4},\ "
     r"\left(\frac{5 - \frac{1}{x}}{4}\right),\ \ldots$",
 
     3: r"$\sqrt{2},\ \sqrt[3]{x},\ \ldots$",

lib/matplotlib/cbook/deprecation.py

@@ -86,18 +86,18 @@ def warn_deprecated(
         If True, uses a PendingDeprecationWarning instead of a
         DeprecationWarning.  Cannot be used together with *removal*.
 
-    removal : str, optional
-        The expected removal version.  With the default (an empty string), a
-        removal version is automatically computed from *since*.  Set to other
-        Falsy values to not schedule a removal date.  Cannot be used together
-        with *pending*.
-
     obj_type : str, optional
         The object type being deprecated.
 
     addendum : str, optional
         Additional text appended directly to the final message.
 
+    removal : str, optional
+        The expected removal version.  With the default (an empty string), a
+        removal version is automatically computed from *since*.  Set to other
+        Falsy values to not schedule a removal date.  Cannot be used together
+        with *pending*.
+
     Examples
     --------
 
@@ -157,15 +157,19 @@ def new_function():
         If True, uses a PendingDeprecationWarning instead of a
         DeprecationWarning.  Cannot be used together with *removal*.
 
+    obj_type : str, optional
+        The object type being deprecated; by default, 'function' if decorating
+        a function and 'class' if decorating a class.
+
+    addendum : str, optional
+        Additional text appended directly to the final message.
+
     removal : str, optional
         The expected removal version.  With the default (an empty string), a
         removal version is automatically computed from *since*.  Set to other
         Falsy values to not schedule a removal date.  Cannot be used together
         with *pending*.
 
-    addendum : str, optional
-        Additional text appended directly to the final message.
-
     Examples
     --------
 
@@ -176,16 +180,12 @@ def the_function_to_deprecate():
                 pass
     """
 
-    if obj_type is not None:
-        warn_deprecated(
-            "3.0", message="Passing 'obj_type' to the 'deprecated' decorator "
-            "has no effect, and is deprecated since Matplotlib %(since)s; "
-            "support for it will be removed %(removal)s.")
-
     def deprecate(obj, message=message, name=name, alternative=alternative,
                   pending=pending, addendum=addendum):
+
         if isinstance(obj, type):
-            obj_type = "class"
+            if obj_type is None:
+                obj_type = "class"
             func = obj.__init__
             name = name or obj.__name__
             old_doc = obj.__doc__
@@ -225,7 +225,8 @@ def finalize(_, new_doc):
                     fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc)
 
         else:
-            obj_type = "function"
+            if obj_type is None:
+                obj_type = "function"
             func = obj
             name = name or obj.__name__
             old_doc = func.__doc__

lib/matplotlib/mathtext.py

@@ -3183,6 +3183,8 @@ def dfrac(self, s, loc, toks):
         return self._genfrac('', '', thickness,
                              self._math_style_dict['displaystyle'], num, den)
 
+    @cbook.deprecated("3.1", obj_type="mathtext command",
+                      alternative=r"\genfrac")
     def stackrel(self, s, loc, toks):
         assert len(toks) == 1
         assert len(toks[0]) == 2

tutorials/text/mathtext.py

@@ -80,15 +80,16 @@
 -----------------------------------------
 
 Fractions, binomials, and stacked numbers can be created with the
-``\frac{}{}``, ``\binom{}{}`` and ``\stackrel{}{}`` commands, respectively::
+``\frac{}{}``, ``\binom{}{}`` and ``\genfrac{}{}{}{}{}{}`` commands,
+respectively::
 
-    r'$\frac{3}{4} \binom{3}{4} \stackrel{3}{4}$'
+    r'$\frac{3}{4} \binom{3}{4} \genfrac{}{}{0}{}{3}{4}$'
 
 produces
 
 .. math::
 
-    \frac{3}{4} \binom{3}{4} \stackrel{3}{4}
+    \frac{3}{4} \binom{3}{4} \stackrel{}{}{0}{}{3}{4}
 
 Fractions can be arbitrarily nested::