document labelvisibility on shared axes change

ImportanceOfBeingErnest · ImportanceOfBeingErnest · commit 72d20b065890 · 2018-04-08T01:32:04.000+02:00
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -407,6 +407,16 @@ Both bindings are disabled if only a subset of the grid lines (in either
 direction) is visible, to avoid making irreversible changes to the figure.
 
 
+Ticklabels are turned off instead of being invisible
+----------------------------------------------------
+
+Internally, :func:`~matplotlib.axis.Axis.set_tick_params` is now used to
+hide tick labels instead of setting the visibility on the tick label objects.
+This improves overall performance and fixes some issues.
+As a consequence, in case those labels ought to be shown, `set_tick_params`
+needs to be used, e.g. `ax.xaxis.set_tick_params(labelbottom=True)`.
+
+
 Removal of warning on empty legends
 -----------------------------------
 
diff --git a/doc/users/prev_whats_new/whats_new_2.1.0.rst b/doc/users/prev_whats_new/whats_new_2.1.0.rst
@@ -403,6 +403,16 @@ keyword.
     ax.xaxis.set_tick_params(which='both', rotation=90)
 
 
+Ticklabels are turned off instead of being invisible
+----------------------------------------------------
+
+Internally, :func:`~matplotlib.axis.Axis.set_tick_params` is now used to
+hide tick labels instead of setting the visibility on the tick label objects.
+This improves overall performance and fixes some issues.
+As a consequence, in case those labels ought to be shown, `set_tick_params`
+needs to be used, e.g. `ax.xaxis.set_tick_params(labelbottom=True)`.
+
+
 Shading in 3D bar plots
 -----------------------
 
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1265,21 +1265,21 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
                 - 'col': each subplot column will share an x- or y-axis.
 
             When subplots have a shared x-axis along a column, only the x tick
-            labels of the bottom subplot are visible.  Similarly, when
-            subplots have a shared y-axis along a row, only the y tick labels
-            of the first column subplot are visible.
+            labels of the bottom subplot are created. Similarly, when subplots
+            have a shared y-axis along a row, only the y tick labels of the
+            first column subplot are created. To later turn other subplots'
+            ticklabels on, use :meth:`~matplotlib.axis.Axis.set_tick_params`.
 
-        squeeze : bool, default: True
-            - If True, extra dimensions are squeezed out from the returned
-              axis object:
+        squeeze : bool, optional, default: True
+            - If True, extra dimensions are squeezed out from the returned Axes
+              object:
 
                 - if only one subplot is constructed (nrows=ncols=1), the
                   resulting single Axes object is returned as a scalar.
-                - for Nx1 or 1xN subplots, the returned object is a 1D numpy
-                  object array of Axes objects are returned as numpy 1D
-                  arrays.
-                - for NxM, subplots with N>1 and M>1 are returned as a 2D
-                  arrays.
+                - for Nx1 or 1xM subplots, the returned object is a 1D numpy
+                  object array of Axes objects.
+                - for NxM, subplots with N>1 and M>1 are returned
+                  as a 2D array.
 
             - If False, no squeezing at all is done: the returned Axes object
               is always a 2D array containing Axes instances, even if it ends
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1012,19 +1012,20 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
             - 'col': each subplot column will share an x- or y-axis.
 
         When subplots have a shared x-axis along a column, only the x tick
-        labels of the bottom subplot are visible.  Similarly, when subplots
+        labels of the bottom subplot are created. Similarly, when subplots
         have a shared y-axis along a row, only the y tick labels of the first
-        column subplot are visible.
+        column subplot are created. To later turn other subplots' ticklabels
+        on, use :meth:`~matplotlib.axis.Axis.set_tick_params`.
 
     squeeze : bool, optional, default: True
         - If True, extra dimensions are squeezed out from the returned Axes
           object:
 
             - if only one subplot is constructed (nrows=ncols=1), the
               resulting single Axes object is returned as a scalar.
-            - for Nx1 or 1xN subplots, the returned object is a 1D numpy
-              object array of Axes objects are returned as numpy 1D arrays.
-            - for NxM, subplots with N>1 and M>1 are returned as a 2D arrays.
+            - for Nx1 or 1xM subplots, the returned object is a 1D numpy
+              object array of Axes objects.
+            - for NxM, subplots with N>1 and M>1 are returned as a 2D array.
 
         - If False, no squeezing at all is done: the returned Axes object is
           always a 2D array containing Axes instances, even if it ends up
