subplots and figure docstring changes

fredrik-1 · fredrik-1 · commit 00fbb7d08f65 · 2018-06-07T21:50:11.000+02:00
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1254,10 +1254,13 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
         """
         Add a set of subplots to this figure.
 
+        This utility wrapper makes it convenient to create common layouts of
+        subplots in a single call.
+
         Parameters
         ----------
-        nrows, ncols : int, default: 1
-            Number of rows/cols of the subplot grid.
+        nrows, ncols : int, optional, default: 1
+            Number of rows/columns of the subplot grid.
 
         sharex, sharey : bool or {'none', 'all', 'row', 'col'}, default: False
             Controls sharing of properties among x (`sharex`) or y (`sharey`)
@@ -1291,25 +1294,27 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
               is always a 2D array containing Axes instances, even if it ends
               up being 1x1.
 
-        subplot_kw : dict, default: {}
+        subplot_kw : dict, optional
             Dict with keywords passed to the
             :meth:`~matplotlib.figure.Figure.add_subplot` call used to create
-            each subplots.
+            each subplot.
 
-        gridspec_kw : dict, default: {}
+        gridspec_kw : dict, optional
             Dict with keywords passed to the
-            :class:`~matplotlib.gridspec.GridSpec` constructor used to create
+            `~matplotlib.gridspec.GridSpec` constructor used to create
             the grid the subplots are placed on.
 
         Returns
         -------
-        ax : single Axes object or array of Axes objects
-            The added axes.  The dimensions of the resulting array can be
-            controlled with the squeeze keyword, see above.
+        ax : 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 : pyplot API; docstring includes examples.
+        :func:`.pyplot.subplots`: docstring includes examples.
         """
 
         if isinstance(sharex, bool):
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -426,43 +426,46 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
         `num`.
 
     figsize : tuple of integers, optional, default: None
-        width, height in inches. If not provided, defaults to rc
-        figure.figsize.
+        width, height in inches. If not provided, defaults to
+        :rc:`figure.figsize` = ``[6.4, 4.8]``.
 
     dpi : integer, optional, default: None
-        resolution of the figure. If not provided, defaults to rc figure.dpi.
+        resolution of the figure. If not provided, defaults to
+        :rc:`figure.dpi` = ``100``.
 
     facecolor :
-        the background color. If not provided, defaults to rc figure.facecolor.
+        the background color. If not provided, defaults to
+        :rc:`figure.facecolor` = ``'w'``.
 
     edgecolor :
-        the border color. If not provided, defaults to rc figure.edgecolor.
+        the border color. If not provided, defaults to
+        :rc:`figure.edgecolor` = ``'w'``.
 
     frameon : bool, optional, default: True
         If False, suppress drawing the figure frame.
 
-    FigureClass : class derived from matplotlib.figure.Figure
-        Optionally use a custom Figure instance.
+    FigureClass : subclass of `~matplotlib.figure.Figure`
+        Optionally use a custom `.Figure` instance.
 
     clear : bool, optional, default: False
         If True and the figure already exists, then it is cleared.
 
     Returns
     -------
-    figure : Figure
-        The Figure instance returned will also be passed to new_figure_manager
-        in the backends, which allows to hook custom Figure classes into the
-        pylab interface. Additional kwargs will be passed to the figure init
-        function.
+    figure : `~matplotlib.figure.Figure`
+        The `.Figure` instance returned will also be passed to new_figure_manager
+        in the backends, which allows to hook custom `.Figure` classes into the
+        pyplot interface. Additional kwargs will be passed to the `.Figure`
+        init function.
 
     Notes
     -----
-    If you are creating many figures, make sure you explicitly call "close"
-    on the figures you are not using, because this will enable pylab
-    to properly clean up the memory.
+    If you are creating many figures, make sure you explicitly call
+    :func:`.pyplot.close` on the figures you are not using, because this will
+    enable pyplot to properly clean up the memory.
 
-    rcParams defines the default values, which can be modified in the
-    matplotlibrc file.
+    `~matplotlib.rcParams` defines the default values, which can be modified
+    in the matplotlibrc file.
     """
 
     if figsize is None:
@@ -1020,7 +1023,7 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
 
     squeeze : bool, optional, default: True
         - If True, extra dimensions are squeezed out from the returned
-          array of Axes:
+          array of `~matplotlib.axes.Axes`:
 
             - if only one subplot is constructed (nrows=ncols=1), the
               resulting single Axes object is returned as a scalar.
@@ -1038,20 +1041,19 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
         subplot.
 
     gridspec_kw : dict, optional
-        Dict with keywords passed to the
-        :class:`~matplotlib.gridspec.GridSpec` constructor used to create the
-        grid the subplots are placed on.
+        Dict with keywords passed to the `~matplotlib.gridspec.GridSpec`
+        constructor used to create the grid the subplots are placed on.
 
     **fig_kw :
-        All additional keyword arguments are passed to the :func:`figure` call.
+        All additional keyword arguments are passed to the
+        :func:`.pyplot.figure` call.
 
     Returns
     -------
-    fig : :class:`matplotlib.figure.Figure` object
+    fig : `~matplotlib.figure.Figure`
 
     ax : Axes object or array of Axes objects.
-
-        ax can be either a single :class:`matplotlib.axes.Axes` object or an
+        *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.
@@ -1098,10 +1100,17 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
 
     >>> plt.subplots(2, 2, sharex=True, sharey=True)
 
+    Creates figure number 10 with a single subplot
+    and clears it if it already exists.
+
+    >>> fig, ax=plt.subplots(num=10, clear=True)
+
     See Also
     --------
-    figure
-    subplot
+    :func:`.pyplot.figure`
+    :func:`.pyplot.subplot`
+    :meth:`.Figure.add_subplot`
+    :meth:`.Figure.subplots`
     """
     fig = figure(**fig_kw)
     axs = fig.subplots(nrows=nrows, ncols=ncols, sharex=sharex, sharey=sharey,
