Why and overview

Author: lukelbd

docs/overview.rst

@@ -4,8 +4,6 @@ Quick overview
 
 ProPlot is an object-oriented matplotlib wrapper for making beautiful, publication-quality graphics. Most of its features derive from subclasses of the `~matplotlib.figure.Figure` and `~matplotlib.axes.Axes` classes.
 
-If you tend to use the `~matplotlib.pyplot` API and are not familiar with the "axes" and "figure" classes, you should first take a look at `this page <https://matplotlib.org/api/api_overview.html#the-pyplot-api>`__. Using axes and figure objects directly is *much* more clear and concise than using the `~matplotlib.pyplot` API. And changing settings for more than one axes at once gets really cumbersome with `~matplotlib.pyplot`.
-
 This page is meant as the starting point for new users. It is
 populated with links to the :ref:`API reference` and User Guide.
 For more in-depth descriptions, see :ref:`Why ProPlot?`.
@@ -37,20 +35,18 @@ and is packed with new features -- one highlight is the new :ref:`Figure tight l
 algorithm applied to all `~proplot.subplots.Figure`\ s by default.
 See :ref:`Creating figures` for details.
 
-Figure and axes commands
-========================
+Figure and axes methods
+=======================
 The new `~proplot.subplots.Figure` and `~proplot.axes.Axes` classes
 override various matplotlib methods to implement tons of useful features.
 
 The most important new method is `~proplot.axes.Axes.format`. This is available on every axes subclass generated by proplot -- `~proplot.axes.XYAxes`, `~proplot.axes.PolarAxes`, and `~proplot.axes.ProjAxes`. Use this method to fine-tune your axis properties, titles, labels, limits, arbitrary settings, and much much more.
 See :ref:`Customizing figures` for details.
 
-Outer colorbars and legends
-===========================
-Proplot adds new `~proplot.axes.Axes` `~proplot.axes.Axes.colorbar` and `~proplot.axes.Axes.legend` commands and `~proplot.subplots.Figure` `~proplot.subplots.Figure.colorbar` and `~proplot.subplots.Figure.legend` commands that make adding colorbars and legends to the *outside* of axes simple.
-See :ref:`Colorbars and legends` for details.
+Proplot adds new `~proplot.axes.Axes` `~proplot.axes.Axes.colorbar` and `~proplot.axes.Axes.legend` commands and `~proplot.subplots.Figure` `~proplot.subplots.Figure.colorbar` and `~proplot.subplots.Figure.legend` commands that make adding colorbars and legends to the *outside* of axes simple. See :ref:`Colorbars and legends` for details.
 
-The `~proplot.subplots.Figure` methods align objects with respect to the subplot grid, rather than the figure bounds. You can also make inset colorbars, make colorbars from lists of lines or colors, and make legends with centered rows instead of aligned columns.
+ProPlot also wraps several plotting methods on the `~proplot.axes.Axes` class.
+See :ref:`1d plotting` and :ref:`2d plotting` for details.
 
 Integration with other packages
 ===============================

docs/why.rst

@@ -137,11 +137,10 @@ Simpler colorbars and legends
 
    <h3>Problem</h3>
 
-In matplotlib, it is hard to put colorbars and legends on the outside of subplots. It can end up messing up subplot aspect ratios, and colorbars tend to be too narrow or too wide.
+In matplotlib, it is hard to draw `~matplotlib.figure.Figure.colorbar`\ s and
+`~matplotlib.axes.Axes.legend`\ s on the outside of subplots. It can end up messing up subplot aspect ratios, and colorbars tend to be too narrow or too wide.
 
-It is *also* difficult to draw colorbars and legends that span the figure edge or serve as reference to more than one subplot.
-Because this requires so much tinkering, most users just add identical colorbars
-to every single subplot, which is incredibly repetitive!
+It is *also* difficult to draw `~matplotlib.figure.Figure.colorbar`\ s and `~matplotlib.figure.Figure.legend`\ s that span the figure edge or reference more than one subplot. "Figure colorbars" require drawing your own dedicated colorbar axes, which requires so much tinkering that most users just add identical colorbars to every single subplot! Meanwhile legends tend to look misaligned -- they are centered with respect to the figure edges rather than the subplot grid, which is a problem if your left-right or top-bottom border padding is asymmetric.
 
 ..
    Drawing colorbars and legends is pretty clumsy in matplotlib -- especially when trying to draw them outside of the figure. They can be too narrow, too wide, and mess up your subplot aspect ratios.
@@ -153,12 +152,9 @@ to every single subplot, which is incredibly repetitive!
 ProPlot introduces a brand new engine for drawing colorbars and legends along the outside of
 individual subplots and along contiguous subplots on the edge of the figure:
 
-* The `~proplot.axes.Axes` `~proplot.axes.Axes.legend` command and the `~proplot.subplots.Figure` `~proplot.subplots.Figure.colorbar` and `~proplot.subplots.Figure.legend` commands are overridden, adding various new features.
-* There is a new `~proplot.axes.Axes` `~proplot.axes.Axes.colorbar` method for drawing *inset* colorbars or adding colorbars along the outer edge of axes.
-* The `~proplot.subplots.Figure` `~proplot.subplots.Figure.colorbar` and `~proplot.subplots.Figure.legend` commands draw colorbars and legends that are centered relative to the *subplot grid*, not the axes. This is critical if your left-right or top-bottom border padding is asymmetric.
-* You can put colorbars and legends along the edge of axes or along the edge of the whole figure by passing ``loc='l'``, ``loc='r'``, ``loc='b'``, or ``loc='t'`` to the colorbar and legend commands.
-* Outer colorbars and legends don't mess up the subplot layout or subplot aspect ratios, since the new `~proplot.subplots.FlexibleGridSpec` class permits variable spacing between subplot rows and columns. This is critical e.g. if you have a colorbar between columns 1 and 2 but nothing between columns 2 and 3.
-* The width of colorbars are now specified in physical units. This makes it easier to get the thickness just right, and makes thickness independent of figure size.
+* The `~proplot.axes.Axes` `~proplot.axes.Axes.legend` command and the `~proplot.subplots.Figure` `~proplot.subplots.Figure.colorbar` and `~proplot.subplots.Figure.legend` commands are overridden, adding various new features like colorbars-from-lines and centered-row legends. There is also a new `~proplot.axes.Axes` `~proplot.axes.Axes.colorbar` method for drawing *inset* colorbars or colorbars along the outer edge of axes.
+* Passing ``loc='l'``, ``loc='r'``, ``loc='b'``, or ``loc='t'`` to `~proplot.axes.Axes` `~proplot.axes.Axes.colorbar` or `~proplot.axes.Axes` `~proplot.axes.Axes.legend` draws the colorbar or legend along outside of the axes. Passing these to `~proplot.subplots.Figure` `~proplot.subplots.Figure.colorbar` and `~proplot.subplots.Figure.legend` draws the colorbar or legend along the edge of the figure, centered relative to the *subplot grid* rather than figure coordinates.
+* Outer colorbars and legends don't mess up the subplot layout or subplot aspect ratios, since the new `~proplot.subplots.FlexibleGridSpec` class permits variable spacing between subplot rows and columns. This is critical e.g. if you have a colorbar between columns 1 and 2 but nothing between columns 2 and 3. Colorbar widths are also specified in physical units, which makes the thickness independent of figure size and makes it easier to get the thickness just right.
 
 The axes container class
 ========================