Overview and why-proplot, split nb_setup() into 3 funcs

Author: lukelbd

docs/faq.rst

@@ -33,7 +33,7 @@ Why do my inline figures look different?
 
 These days, most publications prefer plots saved as `vector graphics <https://en.wikipedia.org/wiki/Vector_graphics>`__ [1]_ rather than `raster graphics <https://en.wikipedia.org/wiki/Raster_graphics>`__ [2]_. When you save vector graphics, the content sizes should be appropriate for embedding the plot in a document (for example, if an academic journal recommends 8-point font for plots, you should use 8-point font in your plotting code).
 
-Matplotlib tends to generate really low-resolution, artifact-plagued jpegs -- and to keep them legible, they use a fairly large default figure width of 6.5 inches (usually only suitable for multi-panel plots) and a fairly large default font size of 10 points (where most journals recommend 5-9 points). This means your figures have to be downscaled, so the sizes used in your plotting code are not the sizes that appear in the document.
+Most of the default matplotlib backends make low-quality, artifact-plagued jpegs. To keep them legible, matplotlib uses a fairly large default figure width of 6.5 inches (usually only suitable for multi-panel plots) and a slightly large default font size of 10 points (where most journals recommend 5-9 points). This means your figures have to be downscaled so the sizes used in your plotting code are *not* the sizes that appear in the document.
 
 ProPlot helps you get your figure sizes *correct* for embedding
 them as vector graphics inside publications.

docs/overview.rst

@@ -1,12 +1,17 @@
 ==============
-Quick overview
+Usage 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.
+ProPlot is an *object-oriented* matplotlib wrapper, which means
+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 figure and axes "objects", you should first take a look at `this page <https://matplotlib.org/api/api_overview.html#the-pyplot-api>`__. Using the objects directly tends to be more clear and concise than `~matplotlib.pyplot` API, and makes life easier when working with multiple figures or axes.
 
-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?`.
+..
+   This page gives a condensed overview of these features, along with features
+   outside of these classes.
+..
+   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?`.
 
 Importing proplot
 =================
@@ -17,36 +22,28 @@ We recommend importing ProPlot with
 
    import proplot as plot
 
-This differentiates ProPlot from the usual ``plt`` abbreviation used for the `~matplotlib.pyplot` module.
+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 a bunch of new colormaps, property cyclers, color names, and fonts to matplotlib and changes some default settings.
-If this is all you want and you don't care about the plotting features, simply
-``import proplot`` at the top of your script. See :ref:`Colormaps`, :ref:`Color cycles`, and :ref:`Colors and fonts` for details.
-
-Top-level commands
-==================
-
-ProPlot's features derive from the `~proplot.subplots.subplots` command, inspired
-by the pyplot `~matplotlib.pyplot.subplots` command.
-
-The `~proplot.subplots.subplots` command creates a `~proplot.subplots.Figure` subclass
-populated with special `~proplot.axes.Axes` subclasses,
-and is packed with new features -- one highlight is the new :ref:`Figure tight layout`
-algorithm applied to all `~proplot.subplots.Figure`\ s by default.
-See :ref:`Creating figures` for details.
-
-Figure and axes methods
+Figure and axes classes
 =======================
-The new `~proplot.subplots.Figure` and `~proplot.axes.Axes` classes
-override various matplotlib methods to implement tons of useful features.
+ProPlot's features derive from `~proplot.subplots.subplots`, modeled after
+the native `matplotlib.pyplot.subplots` command.
+`~proplot.subplots.subplots` creates a `~proplot.subplots.Figure` subclass
+populated with special `~proplot.axes.Axes` subclasses.
+See :ref:`Creating figures`
+and :ref:`Figure tight layout` for details.
 
-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.
+Each `~proplot.axes.Axes` class also belongs to
+one of the `~proplot.axes.XYAxes`, `~proplot.axes.PolarAxes`,
+or `~proplot.axes.ProjAxes` parent classes, depending on the projection used. See
+:ref:`Geographic and polar plots` 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` and `~proplot.axes.Axes` subclasses
+include useful new methods and override several existing methods:
 
-ProPlot also wraps several plotting methods on the `~proplot.axes.Axes` class.
-See :ref:`1d plotting` and :ref:`2d plotting` for details.
+* The most important new method is `~proplot.axes.Axes.format`, whose behavior depends on whether the axes is an `~proplot.axes.XYAxes`, `~proplot.axes.PolarAxes`, or `~proplot.axes.ProjAxes`. This method fine-tunes various axes settings. See :ref:`Customizing figures` for details.
+* The `~proplot.subplots.Figure` `~proplot.subplots.Figure.colorbar` and `~proplot.subplots.Figure.legend` and `~proplot.axes.Axes` `~proplot.axes.Axes.colorbar` and `~proplot.axes.Axes.legend` commands are used to add colorbars and legends *inside* of subplots, along the *outside edge* of subplots, and along the *edge of the figure*. See :ref:`Colorbars and legends` for details.
+* There is a huge variety of new features for working with contour plots, pcolor plots, heatmaps, line plots, error bars, bar plots, area plots, and parametric plots. See :ref:`1d plotting` and :ref:`2d plotting` for details.
 
 Integration with other packages
 ===============================
@@ -55,9 +52,9 @@ ProPlot includes integration with `xarray`, `pandas`, `cartopy`, and `~mpl_toolk
 * Axis labels, tick labels, titles, colorbar labels, and legend labels are automatically applied when you pass an `xarray.DataArray`, `pandas.DataFrame`, or `pandas.Series` object to any plotting command. This works just like the native `xarray.DataArray.plot` and `pandas.DataFrame.plot` methods. See :ref:`1d plotting` and :ref:`2d plotting` for details.
 * The `~proplot.projs.Proj` function lets you make arbitrary grids of basemap `~mpl_toolkits.basemap.Basemap` and cartopy `~cartopy.crs.Projection` projections. It is used to interpret the `proj` keyword arg passed to `~proplot.subplots.subplots`. The resulting axes are instances of `~proplot.axes.ProjAxes` with `~proplot.axes.ProjAxes.format` methods that can be used to add geographic features and custom meridian and parallel gridlines. See :ref:`Geographic and polar plots` for details.
 
-Additional tools
-================
-ProPlot includes a bunch of additional tools outside
+Other functions and classes
+===========================
+ProPlot includes a bunch of useful tools outside
 of the `~proplot.subplots.Figure` and `~proplot.axes.Axes` subclasses:
 
 * The `~proplot.styletools.Colormap` and `~proplot.styletools.Cycle` constructor functions. These can slice, merge, and modify colormaps and color cycles. See :ref:`Colormaps`, :ref:`Color cycles`, and :ref:`Colors and fonts` for details.