Update docs, fix ore gridspec docs bugs

Author: lukelbd

docs/1dplots.py

@@ -182,16 +182,16 @@
 # <https://matplotlib.org/tutorials/intermediate/color_cycle.html#sphx-glr-tutorials-intermediate-color-cycle-py>`__
 # and use different property cycles for different plot elements. You can create and
 # apply property cycles on-the-fly using the `cycle` and `cycle_kw` keywords, available
-# with most 1D plotting commands. `cycle` and `cycle_kw` are passed to the
-# `~proplot.constructor.Cycle` :ref:`constructor function <why_constructor>`, and the
-# resulting property cycle is used for the plot. You can specify `cycle` once with
-# 2D input data (in which case each column is plotted in succession according to
-# the property cycle) or call a plotting command multiple times with the same
-# `cycle` argument each time (the property cycle is not reset). You can also
-# disable property cycling with ``cycle=False``, ``cycle='none'``, or ``cycle=()``
-# and re-enable the default property cycle with ``cycle=True``. For more information
-# on property cycling, see the :ref:`color cycles section <ug_cycles>` and
-# `this matplotlib tutorial
+# with most `~proplot.axes.PlotAxes` 1D plotting commands. `cycle` and `cycle_kw` are
+# passed to the `~proplot.constructor.Cycle` :ref:`constructor function
+# <why_constructor>`, and the resulting property cycle is used for the plot. You
+# can specify `cycle` once with 2D input data (in which case each column is
+# plotted in succession according to the property cycle) or call a plotting
+# command multiple times with the same `cycle` argument each time (the property
+# cycle is not reset). You can also disable property cycling with
+# ``cycle=False``, ``cycle='none'``, or ``cycle=()`` and re-enable the default
+# property cycle with ``cycle=True``. For more information on property cycling,
+# see the :ref:`color cycles section <ug_cycles>` and `this matplotlib tutorial
 # <https://matplotlib.org/tutorials/intermediate/color_cycle.html#sphx-glr-tutorials-intermediate-color-cycle-py>`__.
 
 # %%
@@ -490,16 +490,17 @@
 # `~proplot.axes.PlotAxes.scatterx`. `~proplot.axes.PlotAxes.bar`, and
 # `~proplot.axes.PlotAxes.barh` plots using any of several keyword arguments.
 #
-# If you pass 2D arrays to these commands with ``mean=True`` or ``median=True``,
-# the means or medians of each column are drawn as lines, points, or bars, while
-# *error bars* or *error shading* indicates the spread of the distribution
-# for each column. Invalid data is ignored. You can also specify the error bounds
-# *manually* with the `bardata`, `boxdata`, `shadedata`, and `fadedata` keywords.
-# These commands can draw and style thin error bars (the ``bar`` keywords), thick
-# "boxes" overlaid on top of these bars (the ``box`` keywords; think of them as
-# miniature boxplots), a transparent shading region (the ``shade`` keywords), and
-# a more transparent secondary shading region (the ``fade`` keywords). See the
-# documentation on the plotting commands for details.
+# If you pass 2D arrays to these commands with ``mean=True``, ``means=True``,
+# ``median=True``, or ``medians=True``, the means or medians of each column are
+# drawn as lines, points, or bars, while *error bars* or *error shading*
+# indicates the spread of the distribution in each column. Invalid data is
+# ignored. You can also specify the error bounds *manually* with the `bardata`,
+# `boxdata`, `shadedata`, and `fadedata` keywords. These commands can draw and
+# style thin error bars (the ``bar`` keywords), thick "boxes" overlaid on top of
+# these bars (the ``box`` keywords; think of them as miniature boxplots), a
+# transparent primary shading region (the ``shade`` keywords), and a more
+# transparent secondary shading region (the ``fade`` keywords). See the documentation
+# on the plotting commands for details.
 
 
 # %%
@@ -704,14 +705,14 @@
 # Parametric plots
 # ----------------
 #
-# To make "parametric" plots, use the new `~proplot.axes.PlotAxes.parametric`
-# command. Parametric plots are `~matplotlib.collections.LineCollection`\ s that
-# map individual line segments to individual colors, where each segment represents a
+# Parametric plots can be drawn using the new `~proplot.axes.PlotAxes.parametric`
+# command. This creates `~matplotlib.collections.LineCollection`\ s that map
+# individual line segments to individual colors, where each segment represents a
 # "parametric" coordinate (e.g., time). The parametric coordinates are specified with
-# the `values` keyword argument. See `~proplot.axes.PlotAxes.parametric` for details.
-# As shown below, it is also easy to build colorbars from the
-# `~matplotlib.collections.LineCollection` returned by
-# `~proplot.axes.PlotAxes.parametric`.
+# a third positional argument or with the keywords `c`, `color`, `colors` or `values`.
+# Representing parametric coordinates with colors instead of text labels can be
+# cleaner. The below example makes a simple `~proplot.axes.PlotAxes.parametric`
+# plot with a colorbar indicating the parametric coordinate.
 
 # %%
 import proplot as pplt

docs/2dplots.py

@@ -183,18 +183,19 @@
 # It is often useful to create `~proplot.colors.ContinuousColormap`\ s
 # on-the-fly, without explicitly calling the `~proplot.constructor.Colormap`
 # :ref:`constructor function <why_constructor>`. You can do so using the `cmap`
-# and `cmap_kw` keywords. For example, to create and apply a monochromatic
-# colormap, you can use ``cmap='color_name'`` (see the :ref:`colormaps section
-# <ug_cmaps>` for more info). You can also create on-the-fly "qualitative"
-# `~proplot.colors.DiscreteColormap`\ s by passing lists of colors to
-# the keyword `c`, `color`, or `colors`.
+# and `cmap_kw` keywords, available with most `~proplot.axes.PlotAxes` 2d plotting
+# commands. For example, to create and apply a monochromatic colormap, you can use
+# ``cmap='color_name'`` (see the :ref:`colormaps section <ug_cmaps>` for more info).
+# You can also create on-the-fly "qualitative" `~proplot.colors.DiscreteColormap`\ s
+# by passing lists of colors to the keyword `c`, `color`, or `colors`.
 #
 # In matplotlib, data values are translated into
 # colormap colors using so-called `colormap "normalizers"
 # <https://matplotlib.org/stable/tutorials/colors/colormapnorms.html>`__.
 # A normalizer can be selected from its "registered" name using the
 # `~proplot.constructor.Norm` :ref:`constructor function <why_constructor>`. You
-# can also build a normalizer on-the-fly using the `norm` and `norm_kw` keywords.
+# can also build a normalizer on-the-fly using the `norm` and `norm_kw` keywords,
+# again available with most `~proplot.axes.PlotAxes` 2d plotting commands.
 # If you want to work with normalizer classes directly, they are also imported
 # into the top-level namespace (e.g., ``pplt.LogNorm(...)`` is allowed). To
 # explicitly set the normalization range, you can pass the usual `vmin` and `vmax`

docs/basics.py

@@ -26,9 +26,9 @@
 # ----------------
 #
 # ProPlot works by creating a `proplot.figure.Figure` subclass of
-# `matplotlib.figure.Figure`, an `proplot.axes.Axes` subclass of
-# `matplotlib.axes.Axes`, and determining subplot locations using a
-# `proplot.gridspec.GridSpec` subclass of `matplotlib.gridspec.GridSpec`
+# `matplotlib.figure.Figure`, an `proplot.axes.Axes` and `proplot.axes.PlotAxes`
+# subclass of `matplotlib.axes.Axes`, and determining subplot locations using
+# a `proplot.gridspec.GridSpec` subclass of `matplotlib.gridspec.GridSpec`
 # (for more on gridspecs, see this `matplotlib tutorial
 # <https://matplotlib.org/stable/tutorials/intermediate/gridspec.html>`__).
 #
@@ -91,19 +91,22 @@
 # Creating subplots
 # -----------------
 #
-# Similar to matplotlib, subplots can be added to figures one-by-one or all
-# at once. To add subplots all at once, use the `~proplot.figure.Figure.add_subplots`
-# or `~proplot.figure.Figure.subplots` commands.
+# Similar to matplotlib, `proplot.axes.Axes` can be added to figures
+# one-by-one or all at once. To add subplots all at once, use the
+# `~proplot.figure.Figure.add_subplots` or `~proplot.figure.Figure.subplots`
+# commands. Note that under the hood, `~proplot.ui.subplots` simply calls
+# `~proplot.ui.figure` followed by `proplot.figure.Figure.add_subplots`.
 #
-# * With no arguments, `~proplot.figure.Figure.add_subplots` returns a figure
-#   with a single subplot.
+# * With no arguments, `~proplot.figure.Figure.add_subplots` returns single
+#   subplot generated from a 1-column, 1-row `~proplot.gridspec.GridSpec`.
 # * With `ncols` or `nrows`, `~proplot.figure.Figure.add_subplots` returns a
-#   figure with a simple grid of subplots.
-# * With `array`, `~proplot.figure.Figure.add_subplots` returns a figure with
-#   an arbitrarily complex grid of subplots. `array` is a 2D array representing
-#   a "picture" of the subplot layout, where each unique integer indicates a
-#   `~matplotlib.gridspec.GridSpec` slot that is occupied by the corresponding
-#   subplot and ``0`` indicates an empty space.
+#   simple grid of subplots from a `~proplot.gridspec.GridSpec` with
+#   matching geometry in either row-major or column-major `order`.
+# * With `array`, `~proplot.figure.Figure.add_subplots` returns an arbitrarily
+#   complex grid of subplots from a `~proplot.gridspec.GridSpec` with matching
+#   geometry. Here `array` is a 2D array representing a "picture" of the subplot
+#   layout, where each unique integer indicates a `~matplotlib.gridspec.GridSpec` slot
+#   that is occupied by the corresponding subplot and ``0`` indicates an empty space.
 #
 # To add subplots one-by-one, use the `proplot.figure.Figure.add_subplot`
 # or `proplot.figure.Figure.subplot` commands.
@@ -221,9 +224,10 @@
 # an object-oriented interface and a MATLAB-style `~matplotlib.pyplot` interface
 # (which uses the object-oriented interface internally). Plotting with ProPlot is just
 # like plotting with matplotlib's *object-oriented* interface. ProPlot builds upon
-# the `proplot.axes.Axes` base class with a `proplot.axes.PlotAxes` subclass
-# that adds new plotting commands and new features to existing commands. These
-# additions do not change the usage or syntax of existing commands, which
+# the `~matplotlib.axes.Axes` class with a `proplot.axes.PlotAxes` subclass, used
+# with every axes generated by ProPlot. The `~proplot.axes.PlotAxes subclass`
+# adds several new plotting commands and adds new features to existing commands.
+# These additions do not change the usage or syntax of existing commands, which
 # means a shallow learning curve for the average matplotlib user.
 #
 # In the below example, we create a 4-panel figure with the familiar matplotlib

proplot/gridspec.py

@@ -2,8 +2,8 @@
 """
 The gridspec and subplotspec subclasses.
 """
-import functools
 import itertools
+from functools import partial
 
 import matplotlib.axes as maxes
 import matplotlib.gridspec as mgridspec
@@ -69,8 +69,8 @@
     Whether to make the tight layout algorithm apply equal spacing between columns,
     rows, or both. Default is ``False``. Ignored if :rcraw:`tight` is ``False``.
 outerpad : float or str, optional
-    The tight layout padding around edge of figure. Units are interpreted
-    by `~proplot.utils.units`. Default is :rc:`subplots.outerpad`.
+    The tight layout padding around the left, right, top, and bottom edges
+    of the figure.  Default is :rc:`subplots.outerpad`.
     %(units.em)s
 innerpad : float or str, optional
     The scalar tight layout padding between columns and rows. Synonymous with
@@ -83,7 +83,7 @@
 """
 docstring.snippets['gridspec.shared'] = docstring.add_snippets(_shared_docstring)
 docstring.snippets['gridspec.scalar'] = docstring.add_snippets(_scalar_docstring)
-docstring.snippets['gridspec.vector'] = docstring.add_snippets(_tight_docstring)
+docstring.snippets['gridspec.vector'] = docstring.add_snippets(_vector_docstring)
 docstring.snippets['gridspec.tight'] = docstring.add_snippets(_tight_docstring)
 
 
@@ -1112,14 +1112,14 @@ def figure(self, fig):
     # obfuscation makes this confusing. For example gs.update(wspace=gs.wspace) in
     # presence of panels would yield error. For now the only supported introspection
     # is the __repr__. Probably no big deal... introspection not critical here.
-    nrows = property(lambda self: self._nrows)  # in case missing
-    ncols = property(lambda self: self._ncols)  # ...
-    left = property(functools.partial(_get_current_space, key='left'))
-    bottom = property(functools.partial(_get_current_space, key='bottom'))
-    right = property(functools.partial(_get_current_space, key='right'))
-    top = property(functools.partial(_get_current_space, key='top'))
-    hspace = property(functools.partial(_get_current_space, key='hspace'))
-    wspace = property(functools.partial(_get_current_space, key='wspace'))
+    nrows = property(lambda self: self._nrows, doc='')  # in case missing
+    ncols = property(lambda self: self._ncols, doc='')  # ...
+    left = property(partial(_get_current_space, key='left'), doc='')
+    bottom = property(partial(_get_current_space, key='bottom'), doc='')
+    right = property(partial(_get_current_space, key='right'), doc='')
+    top = property(partial(_get_current_space, key='top'), doc='')
+    hspace = property(partial(_get_current_space, key='hspace'), doc='')
+    wspace = property(partial(_get_current_space, key='wspace'), doc='')
     hpad = property(lambda self: list(self._hpad))  # copy for consistency
     wpad = property(lambda self: list(self._wpad))  # ...
     hratios = property(lambda self: list(self._hratios))