Backport PR matplotlib#10981: Document change of label visibility on shared axes

jklymak · MeeseeksDev[bot] · commit e26a5174e503 · 2018-04-25T00:46:41.000Z
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -407,6 +407,22 @@ 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, the `Tick`'s :func:`~matplotlib.axis.Tick.label1On` attribute
+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,
+:func:`~matplotlib.axes.Axes.tick_params`
+needs to be used, e.g.
+
+::
+
+    ax.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
@@ -395,12 +395,28 @@ cases.
 ---------------------------------------------------
 
 Bulk setting of tick label rotation is now possible via
-:func:`~matplotlib.axis.Axis.set_tick_params` using the ``rotation``
+:func:`~matplotlib.axes.Axes.tick_params` using the ``rotation``
 keyword.
 
 ::
 
-    ax.xaxis.set_tick_params(which='both', rotation=90)
+    ax.tick_params(which='both', rotation=90)
+
+
+Ticklabels are turned off instead of being invisible
+----------------------------------------------------
+
+Internally, the `Tick`'s :func:`~matplotlib.axis.Tick.label1On` attribute
+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,
+:func:`~matplotlib.axes.Axes.tick_params`
+needs to be used, e.g.
+
+::
+
+    ax.tick_params(labelbottom=True)
 
 
 Shading in 3D bar plots
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1266,21 +1266,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.axes.Axes.tick_params`.
 
-        squeeze : bool, default: True
+        squeeze : bool, optional, default: True
             - If True, extra dimensions are squeezed out from the returned
-              axis object:
+              array of Axes:
 
                 - 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
@@ -1091,19 +1091,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.axes.Axes.tick_params`.
 
     squeeze : bool, optional, default: True
-        - If True, extra dimensions are squeezed out from the returned Axes
-          object:
+        - If True, extra dimensions are squeezed out from the returned
+          array of Axes:
 
             - 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
