Quick overview and links cleanup

docs/external-links.rst

@@ -8,36 +8,36 @@ or are directly used by ProPlot.
 
 Python packages
 ===============
-* `matplotlib <https://matplotlib.org>`__ - The powerful, comprehensive plotting package that we all know and love.
-* `xarray <http://xarray.pydata.org/en/stable/api.html>`__ - The venerable NetCDF data package. If you haven't heard of it and you work with NetCDF files, it will change your life.
-* `pandas <https://pandas.pydata.org>`__ - Package that turns spreadsheets and tables into annotated numpy arrays. Invaluable for certain types of data.
+* `matplotlib <https://matplotlib.org>`__ - The venerable plotting package that we all know and love.
+* `xarray <http://xarray.pydata.org/en/stable/api.html>`__ - Package for working with annotated ND numpy arrays. If you haven't heard of it and you work with NetCDF files, it will change your life.
+* `pandas <https://pandas.pydata.org>`__ - Package that turns spreadsheets and tables into annotated 2D numpy arrays. Invaluable for certain types of data.
 * `seaborn <https://seaborn.pydata.org>`__ - A statistical data visualization package. It has some awesome features, but few people in my field use it because it is geared more toward statistical data than geophysical data and other data types.
 
-Downloadable Colormaps
+Downloadable colormaps
 ======================
 The following colormap repositories are
 imported and registered by ProPlot.
 
 #. `Color Brewer <http://colorbrewer2.org/#type=sequential&scheme=BuGn&n=3>`__ - The O.G. perceptually uniform colormap distribution. These are included with the matplotlib distribution.
-#. `cmocean <https://matplotlib.org/cmocean/>`__ - Perceptually uniform colormaps designed for oceangoraphy, but suitable for plenty of other applications.
+#. `cmocean <https://matplotlib.org/cmocean/>`__ - Perceptually uniform colormaps designed for oceanography, but suitable for plenty of other applications.
 #. `SciVisColor <https://sciviscolor.org/>`__ - Science-focused colormaps created by the viz team at UT Austin. Provides tools for *merging* and *combining* colormaps, suitable for complex datasets with weird distributions.
 #. `Fabio Crameri <http://www.fabiocrameri.ch/colourmaps.php>`__ - Perceptually uniform colormaps for geosciences.
 
-Design Your Own Colormaps
-=========================
+Tools for making new colormaps
+==============================
 
-Resources for making your own colormaps from scratch.
+Use these resources to make colormaps from scratch.
 
 #. `Proplot API <https://proplot.readthedocs.io/en/latest/colors.html#making-your-own-colormaps>`__
 #. `HCL Picker <http://tristen.ca/hcl-picker/#/hlc/6/1/15534C/E2E062>`__
 #. `Chroma.js <https://gka.github.io/palettes/>`__
 #. `HCL Wizard <http://hclwizard.org:64230/hclwizard/>`__
 #. `SciVisColor <https://sciviscolor.org/home/colormoves/>`__
 
-Design Your Own Color Cycles
-============================
+Tools for making new color cycles
+=================================
 
-Resources for making your own color cycles from scratch.
+Use these resources to make color cycles from scratch.
 
 #. `Proplot API <https://proplot.readthedocs.io/en/latest/colors.html#making-your-own-color-cycles>`__
 #. `Color Cycle Picker <https://colorcyclepicker.mpetroff.net/>`__
@@ -48,6 +48,3 @@ Resources for making your own color cycles from scratch.
 #. `Adobe Color <https://color.adobe.com/explore>`__
 
 
-
-
-

docs/quick-overview.rst

@@ -2,16 +2,18 @@
 Quick overview
 ==============
 
-.. include:: importing.rst
-
-Color usage tools
+Importing proplot
 =================
 
-When you import proplot:
+We recommend importing ProPlot with
+
+.. code-block:: python
 
-* A bunch of new colormaps, property cyclers, color names, and fonts are registered and some default settings are changed.
-* New tools for visualizing, creating, and modifying colormaps and property cyclers are registered.
+   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 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:`Color usage`, `~proplot.styletools.register_cmaps`, `~proplot.styletools.register_cycles`, `~proplot.styletools.register_colors`, and `~proplot.styletools.register_fonts` for details.
 
@@ -20,10 +22,11 @@ Top-level commands
 
 ProPlot's features derive from the `~proplot.subplots.subplots` and `~proplot.subplots.figure` commands, inspired
 by the pyplot `~matplotlib.pyplot.subplots` and `~matplotlib.pyplot.figure`
-commands.
-This creates a special `~proplot.subplots.Figure` subclass, whose `~proplot.subplots.Figure.add_subplot` method draws special `~proplot.axes.Axes` subclasses.
+commands.  These create a `~proplot.subplots.Figure` subclass
+that generates special `~proplot.axes.Axes` subclasses
+when `~proplot.subplots.Figure.add_subplot` is called.
 
-The features provided by `~proplot.subplots.subplots` and `~proplot.subplots.figure` are numerous; check out the :ref:`Introduction` and the :ref:`API reference`.
+The features provided by `~proplot.subplots.subplots` and `~proplot.subplots.figure` are numerous. One highlight is the new `tight layout <https://matplotlib.org/3.1.1/tutorials/intermediate/tight_layout_guide.html>`__ algorithm applied to all figures by default. This allows the figure width and height to vary so that subplot aspect ratios remain fixed, which is particularly useful for grids of map projections and images. Arbitrary physical units, including *metric* units like ``cm`` and ``mm``, can be used for sizing arguments.
 
 Figure and axes commands
 ========================
@@ -32,27 +35,29 @@ 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.CartesianAxes`, `~proplot.axes.PolarAxes`, and `~proplot.axes.ProjectionAxes`. Use this method to fine-tune your axis properties, titles, labels, limits, arbitrary settings, and much much more. Think of this as an improved version of the `~matplotlib.artist.Artist` `~matplotlib.artist.Artist.update` method.
 
-ProPlot also introduces helpful `~proplot.axistools.Locator`, `~proplot.axistools.Formatter`, `~proplot.axistools.Scale`, `~proplot.projs.Proj`, `~proplot.styletools.Norm`, `~proplot.styletools.Colormap`, and `~proplot.styletools.Cycle` constructor functions. These are used to interpret keyword arguments supplied to `~proplot.axes.Axes.format`, `~proplot.figure.Figure.subplots`, and various plotting commands. This means more flexibility and less boilerplate code.
-
-Automatic layout
-================
-ProPlot implements a new `tight layout <https://matplotlib.org/3.1.1/tutorials/intermediate/tight_layout_guide.html>`__ algorithm and automatically applies it by default. The figure width and height are allowed to vary so that subplot aspect ratios remain fixed, which is particularly useful for grids of map projections and images. Arbitrary physical units, including *metric* units like ``cm`` and ``mm``, can be used for sizing arguments.
+Edge stacks
+===========
+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.
 
+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.
 
-Automatic labelling
-===================
-ProPlot automatically applies axis labels, tick labels, titles, colorbar labels, and legend labels when you pass an `xarray.DataArray`, `pandas.DataFrame`, or `pandas.Series` object to any plotting command. This works just like the native `xarray.DataRray.plot` and `pandas.DataFrame.plot` methods.
+Integration with other packages
+===============================
+ProPlot includes integration with `xarray`, `pandas`, `cartopy`, and `~mpl_toolkits.basemap`:
 
-Side stacks
-===========
-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. It centers them with respect to the subplot grid. You can also make **inset** colorbars, colorbars from list of lines or colors, and legends with centered rows instead of aligned columns.
+* 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.
+* The `~proplot.projs.Proj` function lets you make arbitrary grids of map projections by passing a `proj` name to `~proplot.subplots.Figure.add_subplot` or `~proplot.subplots.Figure.subplots`. The resulting axes are instances of `~proplot.axes.ProjectionAxes` with `~proplot.axes.ProjectionAxes.format` that can be used to add geographic features and custom meridian and parallel gridlines.
 
-Styling your figures
-====================
-Beautiful new colormaps, named "color cycles", and easy-to-remember color names. Tools for merging colormaps and making new "perceptually uniform" colormaps on-the-fly. Tools for slicing and modifying existing colormaps.
+Additional tools
+================
+ProPlot includes a bunch of additional tools outside
+of the `~proplot.subplots.Figure` and `~proplot.axes.Axes` subclasses:
 
-You can customize global settings with a user ``.proplotrc`` file. Save custom colormaps, color cycles, and fonts in a user ``.proplot`` folder, and they will be loaded every time on startup.
+* The `~proplot.styletools.Colormap` and `~proplot.styletools.Cycle` constructor functions. These can slice, merge, and modify colormaps and color cycles.
+* The `~proplot.styletools.LinearSegmentedColormap` and  `~proplot.styletools.ListedColormap` subclasses. These are used to wrap the default matplotlib colormaps.
+* The new `~proplot.styletools.PerceptuallyUniformColormap` class, used for creating arbitrary colormaps with perceptually uniform transitions.
+* The `~proplot.rctools.rc` object, an instance of `~proplot.rctools.rc_configurator`, for modifying global settings. You can also control settings with a ``~/.proplotrc`` file. See :ref:`Configuring proplot` for details.
+* The `~proplot.axistools.Locator`, `~proplot.axistools.Formatter`, and `~proplot.axistools.Scale` constructor functions, used to generate class instances from variable input types. These are used to interpret keyword arguments passed to `~proplot.axes.Axes.format` and `~proplot.subplots.Figure.colorbar`.
+* The `~proplot.projs.Proj` constructor function, used to generate basemap `~mpl_toolkits.basemap.Basemap` and cartopy `~cartopy.crs.Projection` instances from shorthand projection names.
+* The `~proplot.styletools.Norm` constructor function, used to generated colormap normalizers from shorthand names; the `~proplot.styletools.LinearSegmentedNorm` normalizer, used to scale colors evenly w.r.t. index for arbitrarily spaced monotonic levels; and the `~proplot.styletools.BinNorm` meta-normalizer, used to discretized colormap colors.
 
-Cartopy and basemap intergration
-================================
-Generate arbitrary grids of arbitrary map projections in one go. Switch between the cartopy and basemap backends painlessly. Simplified plotting commands.  Add geographic features and custom meridian and parallel gridlines and labels with the `~proplot.ProjectionAxes.format` command.