Merge pull request matplotlib#23632 from timhoffm/doc-fixes

Add discouraged admonitions

Author: story645

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