Misc docs cleanup

Author: lukelbd

docs/colorbars_legends.ipynb

@@ -12,7 +12,7 @@
    "metadata": {},
    "source": [
     "## Axes colorbars and legends\n",
-    "ProPlot includes some *awesome* improvements to the default API for working with colorbars and legends to make your life easier."
+    "ProPlot includes some *awesome* improvements to the matplotlib API that make working with colorbars and legends much easier."
    ]
   },
   {
@@ -25,7 +25,7 @@
     "\n",
     "You can also use ProPlot to draw colorbars and legends on-the-fly. To plot data and draw a colorbar in one go, pass a location (e.g. ``colorbar='r'``) to methods that accept a `cmap` argument. To draw a legend or colorbar-legend in one go, pass a location (e.g. ``legend='r'`` or ``colorbar='r'``) to methods that accept a `cycle` argument. These are powered by the `~proplot.wrappers.cmap_changer` and `~proplot.wrappers.cycle_changer` wrappers.\n",
     "\n",
-    "To draw an *inset* colorbar, pass an *inset* location, e.g. ``colorbar='upper right'`` or ``colorbar='ur'``, to methods that accept a `cmap` or `cycle` argument. Inset colorbars have optional rectangular backgrounds, just like inset legends."
+    "You can also draw an *inset* colorbar by passing an *inset* location, e.g. ``colorbar='upper right'`` or ``colorbar='ur'``, to methods that accept a `cmap` or `cycle` argument. Inset colorbars have optional rectangular backgrounds, just like inset legends."
    ]
   },
   {

docs/usage.rst

@@ -32,7 +32,9 @@ We recommend importing ProPlot as follows:
    import proplot as plot
 
 This differentiates ProPlot from the usual ``plt`` abbreviation used for the `~matplotlib.pyplot` module.
-Importing proplot immediately adds a bunch of new colormaps, property cyclers, color names, and fonts to matplotlib. See :ref:`Colormaps`, :ref:`Color cycles`, and :ref:`Colors and fonts` for details.
+Importing ProPlot immediately adds several new colormaps, property cyclers, color names, and fonts to matplotlib. See :ref:`Colormaps`, :ref:`Color cycles`, and :ref:`Colors and fonts` for details.
+
+Importing ProPlot also configures your IPython environment by setting up the matplotlib backend and enabling the autoreload and autosave extensions (this feature can be disabled). See `~proplot.rctools.ipython_matplotlib`, `~proplot.rctools.ipython_autoreload`, and `~proplot.rctools.ipython_autosave` for details.
 
 Figure and axes classes
 =======================

docs/why.rst

@@ -204,12 +204,17 @@ Outer colorbars and legends
 .. rubric:: Problem
 
 In matplotlib, it is difficult to draw `~matplotlib.figure.Figure.colorbar`\ s and
-`~matplotlib.axes.Axes.legend`\ s on the outside of subplots. By default, colorbars "steal" space from their parent subplot, which can mess up subplot aspect ratios. And since colorbar widths are specified in *axes relative* coordinates, they often look "too skinny" or "too fat" after the first draw.
+`~matplotlib.axes.Axes.legend`\ s intended to reference more than one subplot or
+along the outside of subplots:
 
-As with axis labels, it is even more difficult to draw `~matplotlib.figure.Figure.colorbar`\ s and `~matplotlib.figure.Figure.legend`\ s intended to reference more than one subplot:
+* To draw legends outside of subplots, you usually need to position the legend manually and adjust various `~matplotlib.gridspec.GridSpec` spacing properties to make *room* for the legend.
+* To make colorbars that span multiple subplots, you have to supply `~matplotlib.figure.Figure.colorbar` with a `cax` you drew yourself. This requires so much tinkering that most users just add identical colorbars to every single subplot!
+
+Furthermore, drawing colorbars with ``fig.colorbar(..., ax=ax)`` tends to mess up subplot aspect ratios since the space allocated for the colorbar is "stolen" from the parent axes.
+
+..
+   And since colorbar widths are specified in *axes relative* coordinates, they often look "too skinny" or "too fat" after the first draw.
 
-* To make colorbars that span multiple plots, you have to supply `~matplotlib.figure.Figure.colorbar` with a `cax` you drew yourself. This requires so much tinkering that most users just add identical colorbars to every single subplot!
-* To draw legends outside of subplots, e.g. as a reference to *more than one* subplot, you usually need to position the legend manually and adjust various `~matplotlib.gridspec.GridSpec` spacing properties.
 
 ..
    The matplotlib example for `~matplotlib.figure.Figure` legends is `not pretty <https://matplotlib.org/3.1.1/gallery/text_labels_and_annotations/figlegend_demo.html>`__.