Add discouraged admonitions

The [*Discouraged*] prefix in the summary line is added in analogy to
the [*Deprecated*] prefix we add automatically. We do this so that
these "labels" are prominently visible also in summary overviews of
the functions in the docs.

Since we rarely discourage whole functions, for now I just do this
manually.

Author: timhoffm

lib/matplotlib/axes/_axes.py

@@ -1670,7 +1670,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
     def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
                   **kwargs):
         """
-        Plot coercing the axis to treat floats as dates.
+        [*Discouraged*] Plot coercing the axis to treat floats as dates.
 
         .. admonition:: Discouraged
 

lib/matplotlib/axes/_base.py

@@ -2128,19 +2128,23 @@ def get_lines(self):
 
     def get_xaxis(self):
         """
-        Return the XAxis instance.
+        [*Discouraged*] Return the XAxis instance.
 
-        The use of this function is discouraged. You should instead directly
-        access the attribute ``ax.xaxis``.
+        .. admonition:: Discouraged
+
+            The use of this function is discouraged. You should instead
+            directly access the attribute ``ax.xaxis``.
         """
         return self.xaxis
 
     def get_yaxis(self):
         """
-        Return the YAxis instance.
+        [*Discouraged*] Return the YAxis instance.
+
+        .. admonition:: Discouraged
 
-        The use of this function is discouraged. You should instead directly
-        access the attribute ``ax.yaxis``.
+            The use of this function is discouraged. You should instead
+            directly access the attribute ``ax.yaxis``.
         """
         return self.yaxis
 

lib/matplotlib/axis.py

@@ -1851,7 +1851,7 @@ def _format_with_dict(tickd, x, pos):
 
     def set_ticklabels(self, ticklabels, *, minor=False, **kwargs):
         r"""
-        Set the text values of the tick labels.
+        [*Discouraged*] Set the text values of the tick labels.
 
         .. admonition:: Discouraged
 

lib/matplotlib/colorbar.py

@@ -895,7 +895,7 @@ def get_ticks(self, minor=False):
     def set_ticklabels(self, ticklabels, update_ticks=True, *, minor=False,
                        **kwargs):
         """
-        Set tick labels.
+        [*Discouraged*] Set tick labels.
 
         .. admonition:: Discouraged
 

lib/matplotlib/figure.py

@@ -973,7 +973,7 @@ def clear(self, keep_observers=False):
     # synonym for `clear`.
     def clf(self, keep_observers=False):
         """
-        Alias for the `clear()` method.
+        [*Discouraged*] Alias for the `clear()` method.
 
         .. admonition:: Discouraged
 
@@ -2689,7 +2689,8 @@ def get_tight_layout(self):
                      pending=True)
     def set_tight_layout(self, tight):
         """
-        Set whether and how `.tight_layout` is called when drawing.
+        [*Discouraged*] Set whether and how `.tight_layout` is called when
+        drawing.
 
         .. admonition:: Discouraged
 
@@ -2722,8 +2723,10 @@ def get_constrained_layout(self):
                      pending=True)
     def set_constrained_layout(self, constrained):
         """
-        Set whether ``constrained_layout`` is used upon drawing. If None,
-        :rc:`figure.constrained_layout.use` value will be used.
+        [*Discouraged*] Set whether ``constrained_layout`` is used upon
+        drawing.
+
+        If None, :rc:`figure.constrained_layout.use` value will be used.
 
         When providing a dict containing the keys ``w_pad``, ``h_pad``
         the default ``constrained_layout`` paddings will be