Merge pull request matplotlib#29322 from timhoffm/doc-discourage

DOC: Add [*Discouraged*] prefix to summary lines

Author: QuLogic

lib/matplotlib/axes/_base.py

@@ -3602,7 +3602,7 @@ def set_xlabel(self, xlabel, fontdict=None, labelpad=None, *,
 
     def invert_xaxis(self):
         """
-        Invert the x-axis.
+        [*Discouraged*] Invert the x-axis.
 
         .. admonition:: Discouraged
 
@@ -3621,13 +3621,14 @@ def invert_xaxis(self):
     get_xinverted = _axis_method_wrapper("xaxis", "get_inverted")
     xaxis_inverted = _axis_method_wrapper("xaxis", "get_inverted")
     if xaxis_inverted.__doc__:
-        xaxis_inverted.__doc__ += textwrap.dedent("""
+        xaxis_inverted.__doc__ = ("[*Discouraged*] " + xaxis_inverted.__doc__ +
+                                  textwrap.dedent("""
 
         .. admonition:: Discouraged
 
             The use of this method is discouraged.
             Use `.Axes.get_xinverted` instead.
-        """)
+        """))
 
     def get_xbound(self):
         """
@@ -3870,7 +3871,7 @@ def set_ylabel(self, ylabel, fontdict=None, labelpad=None, *,
 
     def invert_yaxis(self):
         """
-        Invert the y-axis.
+        [*Discouraged*]  Invert the y-axis.
 
         .. admonition:: Discouraged
 
@@ -3889,13 +3890,14 @@ def invert_yaxis(self):
     get_yinverted = _axis_method_wrapper("yaxis", "get_inverted")
     yaxis_inverted = _axis_method_wrapper("yaxis", "get_inverted")
     if yaxis_inverted.__doc__:
-        yaxis_inverted.__doc__ += textwrap.dedent("""
+        yaxis_inverted.__doc__ = ("[*Discouraged*] " + yaxis_inverted.__doc__ +
+                                  textwrap.dedent("""
 
         .. admonition:: Discouraged
 
             The use of this method is discouraged.
             Use `.Axes.get_yinverted` instead.
-        """)
+        """))
 
     def get_ybound(self):
         """

lib/matplotlib/axis.py

@@ -1443,7 +1443,7 @@ def set_label(self, s):
 
     def get_label(self):
         """
-        Return the axis label as a Text instance.
+        [*Discouraged*] Return the axis label as a Text instance.
 
         .. admonition:: Discouraged
 

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -1886,7 +1886,7 @@ def tick_params(self, axis='both', **kwargs):
 
     def invert_zaxis(self):
         """
-        Invert the z-axis.
+        [*Discouraged*] Invert the z-axis.
 
         .. admonition:: Discouraged
 
@@ -1906,13 +1906,14 @@ def invert_zaxis(self):
     get_zinverted = _axis_method_wrapper("zaxis", "get_inverted")
     zaxis_inverted = _axis_method_wrapper("zaxis", "get_inverted")
     if zaxis_inverted.__doc__:
-        zaxis_inverted.__doc__ += textwrap.dedent("""
+        zaxis_inverted.__doc__ = ("[*Discouraged*] " + zaxis_inverted.__doc__ +
+                                  textwrap.dedent("""
 
         .. admonition:: Discouraged
 
             The use of this method is discouraged.
             Use `.Axes3D.get_zinverted` instead.
-        """)
+        """))
 
     def get_zbound(self):
         """