Dedupe docs of GridSpec.subplots.

anntzer · anntzer · commit 5c036aa67b6a · 2020-11-26T19:04:50.000+01:00
`GridSpec.subplots`, while user-facing, is relatively more low-level
than `Figure.subplots`, so it doesn't seem worth duplicating the
docstring in both places (I'm fine having it duplicated both in
`pyplot.subplots` and `Figure.subplots` are both are very much
user-facing).  Less duplication also means fewer chances to forget to
update the docs in all places, as was the case for the remark regarding
`set_units` (which is already present in the docs of `pyplot.subplots`,
though).

Also note that a specific check a bit further down can go away once a
deprecation elapses.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -887,6 +887,9 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
             first column subplot are created. To later turn other subplots'
             ticklabels on, use `~matplotlib.axes.Axes.tick_params`.
 
+            When subplots have a shared axis that has units, calling
+            `.Axis.set_units` will update each axis with the new units.
+
         squeeze : bool, default: True
             - If True, extra dimensions are squeezed out from the returned
               array of Axes:
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -266,61 +266,7 @@ def subplots(self, *, sharex=False, sharey=False, squeeze=True,
         """
         Add all subplots specified by this `GridSpec` to its parent figure.
 
-        This utility wrapper makes it convenient to create common layouts of
-        subplots in a single call.
-
-        Parameters
-        ----------
-        sharex, sharey : bool or {'none', 'all', 'row', 'col'}, default: False
-            Controls sharing of properties among x (*sharex*) or y (*sharey*)
-            axes:
-
-            - True or 'all': x- or y-axis will be shared among all subplots.
-            - False or 'none': each subplot x- or y-axis will be independent.
-            - 'row': each subplot row will share an x- or y-axis.
-            - '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 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 `~matplotlib.axes.Axes.tick_params`.
-
-            When subplots have a shared axis that has units, calling
-            `~matplotlib.axis.Axis.set_units` will update each axis with the
-            new units.
-
-        squeeze : bool, optional, default: True
-            - 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 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 being 1x1.
-
-        subplot_kw : dict, optional
-            Dict with keywords passed to the `~.Figure.add_subplot` call used
-            to create each subplot.
-
-        Returns
-        -------
-        ax : `~.axes.Axes` object or array of Axes objects.
-            *ax* can be either a single `~matplotlib.axes.Axes` object or
-            an array of Axes objects if more than one subplot was created. The
-            dimensions of the resulting array can be controlled with the
-            squeeze keyword, see above.
-
-        See Also
-        --------
-        .pyplot.subplots
-        .Figure.add_subplot
-        .pyplot.subplot
+        See `.Figure.subplots` for detailed documentation.
         """
 
         figure = self.figure
@@ -337,7 +283,8 @@ def subplots(self, *, sharex=False, sharey=False, squeeze=True,
         # `subplots(1, 2, 1)` when `subplot(1, 2, 1)` was intended.
         # In most cases, no error will ever occur, but mysterious behavior
         # will result because what was intended to be the subplot index is
-        # instead treated as a bool for sharex.
+        # instead treated as a bool for sharex.  This check should go away
+        # once sharex becomes kwonly.
         if isinstance(sharex, Integral):
             cbook._warn_external(
                 "sharex argument to subplots() was an integer.  Did you "
