From e0ef3ff0ce84479c4691328660542bc51b3e2b27 Mon Sep 17 00:00:00 2001 From: fredrik-1 Date: Tue, 5 Jun 2018 18:49:07 +0200 Subject: [PATCH] subplots and figure docstring changes --- lib/matplotlib/figure.py | 25 +++++++++------- lib/matplotlib/pyplot.py | 63 +++++++++++++++++++++++----------------- 2 files changed, 51 insertions(+), 37 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index e898f9082acd..ac2de0e88daa 100644 --- 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 index e2b5e3747426..a2a40567628b 100644 --- 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,