More docs cleanup

lukelbd · lukelbd · commit c19e637ac67e · 2021-07-02T05:46:36.000-06:00
diff --git a/docs/1dplots.py b/docs/1dplots.py
@@ -18,14 +18,13 @@
 # Plotting 1D data
 # ================
 #
-# ProPlot adds new features to various `~matplotlib.axes.Axes` plotting
-# methods using a set of "wrapper" functions. When a plotting method like
-# `~matplotlib.axes.Axes.plot` is "wrapped" by one of these functions, it
-# accepts the same parameters as the wrapper. These additions are a strict
-# *superset* of matplotlib -- if you are not interested, you
-# can use matplotlib's plotting methods just like you always have.
-# This section documents the features added by wrapper functions to 1D
-# plotting commands like `~matplotlib.axes.Axes.plot`,
+# ProPlot :ref:`adds new features <why_plotting>` to various `~matplotlib.axes.Axes`
+# plotting methods using a set of "wrapper" functions. When a plotting method like
+# `~matplotlib.axes.Axes.plot` is "wrapped" by one of these functions, it accepts
+# the same parameters as the wrapper. These additions are a strict *superset* of
+# matplotlib -- if you are not interested, you can use matplotlib's plotting methods
+# just like you always have. This section documents the features added by wrapper
+# functions to 1D plotting commands like `~matplotlib.axes.Axes.plot`,
 # `~matplotlib.axes.Axes.scatter`, `~matplotlib.axes.Axes.bar`, and
 # `~matplotlib.axes.Axes.barh`.
 
diff --git a/docs/2dplots.py b/docs/2dplots.py
@@ -18,14 +18,13 @@
 # Plotting 2D data
 # ================
 #
-# ProPlot adds new features to various `~matplotlib.axes.Axes` plotting
-# methods using a set of wrapper functions. When a plotting method like
-# `~matplotlib.axes.Axes.contourf` is "wrapped" by one of these functions, it
-# accepts the same parameters as the wrapper. These additions are a strict
-# *superset* of matplotlib -- if you are not interested, you
-# can use matplotlib's plotting methods just like you always have.
-# This section documents the features added by wrapper functions to 2D
-# plotting commands like `~matplotlib.axes.Axes.contour`,
+# ProPlot :ref:`adds new features <why_plotting>` to various `~matplotlib.axes.Axes`
+# plotting methods using a set of "wrapper" functions. When a plotting method like
+# `~matplotlib.axes.Axes.contourf` is "wrapped" by one of these functions, it accepts
+# the same parameters as the wrapper. These additions are a strict *superset* of
+# matplotlib -- if you are not interested, you can use matplotlib's plotting methods
+# just like you always have. This section documents the features added by wrapper
+# functions to 2D plotting commands like `~matplotlib.axes.Axes.contour`,
 # `~matplotlib.axes.Axes.contourf`, `~matplotlib.axes.Axes.pcolor`, and
 # `~matplotlib.axes.Axes.pcolormesh`.
 
diff --git a/docs/basics.py b/docs/basics.py
@@ -263,11 +263,10 @@
 # 2D indexing (e.g., ``axs[0, 1]``), and is row-major by default. Slicing a
 # `~proplot.ui.SubplotsContainer` returns another container (e.g., ``axs[:, 0]``).
 #
-# `~proplot.ui.SubplotsContainer` is useful because it lets you call
-# `~proplot.axes.Axes` methods simultaneously for all subplots in the container.
-# In the below example, we use the `~proplot.ui.SubplotsContainer` returned by
-# `~proplot.ui.subplots` with the `proplot.axes.Axes.format` command to format
-# several subplots at once.
+# `~proplot.ui.SubplotsContainer` also lets you call `~proplot.axes.Axes` methods
+# simultaneously for all subplots in the container. In the below example, we use the
+# `~proplot.ui.SubplotsContainer` returned by `~proplot.ui.subplots` with the
+# `proplot.axes.Axes.format` command to format several subplots at once.
 
 # %%
 import proplot as plot
diff --git a/docs/colorbars_legends.py b/docs/colorbars_legends.py
@@ -19,7 +19,7 @@
 # =====================
 #
 # ProPlot includes some useful improvements to the matplotlib API that make
-# working with colorbars and legends much easier.
+# working with colorbars and legends :ref:`much easier <why_colorbars_legends>`.
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -28,11 +28,11 @@
 # Axes colorbars and legends
 # --------------------------
 #
-# In matplotlib, colorbars are added to the edges of subplots with the *figure* method
-# `matplotlib.figure.Figure.colorbar` using e.g.
-# ``fig.colorbar(m, ax=ax, location='right')``.
-# In ProPlot, colorbars are added using the axes method
-# `proplot.axes.Axes.colorbar` with e.g. ``ax.colorbar(m, loc='r')``.
+# In matplotlib, colorbars are added to the edges of subplots using the figure
+# method `matplotlib.figure.Figure.colorbar`
+# (e.g., ``fig.colorbar(m, ax=ax, location='right')``.
+# In ProPlot, this is done using the axes method
+# `proplot.axes.Axes.colorbar` (e.g., ``ax.colorbar(m, loc='r')``.
 # `proplot.axes.Axes.colorbar` preserves subplot aspect ratios and visual
 # symmetry between subplots by allocating new space in the figure
 # `~proplot.gridspec.GridSpec` rather than "stealing" space from the parent subplot
diff --git a/docs/colormaps.py b/docs/colormaps.py
@@ -27,9 +27,10 @@
 # :ref:`subclassed from <ug_cmaps_new>`
 # `matplotlib.colors.LinearSegmentedColormap`.
 #
-# ProPlot adds several features to help you use colormaps effectively in your
-# figures. This section documents the new registered colormaps, explains how
-# to make and modify colormaps, and shows how to apply them to your plots.
+# ProPlot :ref:`adds several features <why_colormaps_cyles>` to help you use
+# colormaps effectively in your figures. This section documents the new registered
+# colormaps, explains how to make and modify colormaps, and shows how to apply them
+# to your plots.
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
diff --git a/docs/cycles.py b/docs/cycles.py
@@ -31,10 +31,10 @@
 # `~proplot.constructor.Cycle` constructor function or by
 # :ref:`drawing samples <ug_cycles_new>` from continuous colormaps.
 #
-# ProPlot adds several features to help you use color cycles effectively in
-# your figures. This section documents the new registered color cycles,
-# explains how to make and modify colormaps, and shows how to apply them to
-# your plots.
+# ProPlot :ref:`adds several features <why_colormaps_cyles>` to help you use color
+# cycles effectively in your figures. This section documents the new registered
+# color cycles, explains how to make and modify colormaps, and shows how to apply
+# them to your plots.
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
diff --git a/docs/projections.py b/docs/projections.py
@@ -27,8 +27,8 @@
 # ==========================
 #
 # ProPlot includes features for working with `polar axes <polar_>`_ and the
-# `cartopy`_ and `basemap`_ geographic projection packages. These features are
-# optional -- installation of cartopy or basemap is not required.
+# `cartopy`_ and `basemap`_ :ref:`geographic projection packages <why_cartopy_basemap>`.
+# These features are *optional*. Installation of cartopy or basemap is not required.
 #
 # To change the axes projection, pass ``proj='name'`` to `~proplot.ui.subplots`. To use
 # different projections for different subplots, pass a dictionary of projection names
@@ -56,7 +56,6 @@
 # `proplot.axes.PolarAxes.format` calls `proplot.axes.Axes.format`, it can be used to
 # add axes titles, a-b-c labels, and figure titles, just like
 # `~proplot.axes.CartesianAxes`.
-
 #
 # For details, see `proplot.axes.PolarAxes.format`.
 
@@ -102,43 +101,46 @@
 # Geographic axes
 # ---------------
 #
-# ProPlot can create geographic projection axes using either `cartopy`_ or `basemap`_
-# as "backends". To draw geographic axes, pass ``proj='name'`` or e.g.
-# ``proj={2: 'name'}`` (:ref:`see above <ug_proj>`) to  `~proplot.ui.subplots`
-# where ``name`` is any valid :ref:`PROJ projection name <proj_included>`.
-# You can also use ``proj=projection_instance``, where ``projection_instance``
-# is a `cartopy.crs.Projection` or `mpl_toolkits.basemap.Basemap` returned by
-# the `~proplot.constructor.Proj` constructor function.
+# ProPlot can create geographic projection axes using
+# either `cartopy`_ or `basemap`_ as "backends". To draw geographic axes, pass
+# ``proj='name'`` or e.g. ``proj={2: 'name'}`` (:ref:`see above <ug_proj>`) to
+# `~proplot.ui.subplots` where ``name`` is any valid :ref:`PROJ projection name
+# <proj_included>`. You can also use ``proj=projection_instance``, where
+# ``projection_instance`` is a `cartopy.crs.Projection` or
+# `mpl_toolkits.basemap.Basemap` returned by the `~proplot.constructor.Proj`
+# :ref:`constructor function <why_constructor>`.
 #
 # When you request a geographic projection, `~proplot.ui.subplots` returns
 # a `proplot.axes.GeoAxes` instance with its own `~proplot.axes.GeoAxes.format`
-# method. The `proplot.axes.GeoAxes.format` method allows you to
-# :ref:`modify geographic features <ug_geoformat>` with the same syntax whether
-# cartopy or basemap is the "backend". A few details:
+# method. The `proplot.axes.GeoAxes.format` method lets you
+# :ref:`modify geographic features <ug_geoformat>` with the same syntax for
+# either backend. A few details:
 #
 # * Cartopy is the default backend. When you request projections with cartopy as the
 #   backend, `~proplot.ui.subplots` returns `proplot.axes.CartopyAxes`, which is a
-#   subclass of both `cartopy.mpl.geoaxes.GeoAxes` and `proplot.axes.Axes.GeoAxes`.
-#   On `~proplot.axes.CartopyAxes`, `~proplot.axes.GeoAxes.format` changes map
-#   bounds using `~cartopy.mpl.geoaxes.GeoAxes.set_extent`, adds major and minor
-#   gridlines using `~cartopy.mpl.geoaxes.GeoAxes.gridlines`, and adds geographic
-#   features using `~cartopy.mpl.geoaxes.GeoAxes.add_feature`.
-#
-# * Basemap is an alternative backend. To use basemap as the backend, set the
-#   :rcraw:`basemap` setting to ``True`` or pass ``basemap=True`` to
-#   `~proplot.ui.subplots`. When you request projections with basemap as the backend,
-#   `~proplot.ui.subplots` returns `proplot.axes.BasemapAxes`, which is a subclass
-#   of `proplot.axes.GeoAxes`. `~proplot.axes.Axes.BasemapAxes` redirects the plot,
-#   scatter, contour, contourf, pcolor, pcolormesh, quiver, streamplot, and barb
-#   methods to identically named methods on the `~mpl_toolkits.basemap.Basemap`
-#   instance. This means you can work with the standard axes plotting methods rather
-#   than the basemap methods -- just like cartopy. On `~proplot.axes.BasemapAxes`,
-#   `~proplot.axes.GeoAxes.format` adds adds major and minor gridlines using
+#   subclass of both `proplot.axes.GeoAxes` and `cartopy.mpl.geoaxes.GeoAxes`.
+#   Under the hood, invoking `~proplot.axes.GeoAxes.format` on a
+#   `~proplot.axes.CartopyAxes` changes map bounds using
+#   `~cartopy.mpl.geoaxes.GeoAxes.set_extent`, adds major and minor gridlines using
+#   `~cartopy.mpl.geoaxes.GeoAxes.gridlines`, and adds geographic features using
+#   `~cartopy.mpl.geoaxes.GeoAxes.add_feature`. If you prefer, you can use the
+#   standard `cartopy.mpl.geoaxes.GeoAxes` methods just like you would in cartopy.
+#
+# * Basemap is an alternative backend. To use basemap, set :rcraw:`basemap` to
+#   ``True`` or pass ``basemap=True`` to `~proplot.ui.subplots`. When you request
+#   projections with basemap as the backend, `~proplot.ui.subplots` returns
+#   `proplot.axes.BasemapAxes`, which is a subclass of `proplot.axes.GeoAxes`.
+#   `~proplot.axes.BasemapAxes` redirects the plot, scatter, contour, contourf,
+#   pcolor, pcolormesh, quiver, streamplot, and barb methods to identically named
+#   methods on the `~mpl_toolkits.basemap.Basemap` instance. This means you can work
+#   with the standard axes plotting methods rather than the basemap methods -- just
+#   like cartopy. Under the hood, invoking `~proplot.axes.GeoAxes.format` on a
+#   `~proplot.axes.BasemapAxes` adds major and minor gridlines using
 #   `~mpl_toolkits.basemap.Basemap.drawmeridians` and
 #   `~mpl_toolkits.basemap.Basemap.drawparallels` and adds geographic features
 #   using methods like `~mpl_toolkits.basemap.Basemap.fillcontinents`
-#   and `~mpl_toolkits.basemap.Basemap.drawcoastlines`. In case you need to
-#   explicitly use the underlying `~mpl_toolkits.basemap.Basemap` instance, it is
+#   and `~mpl_toolkits.basemap.Basemap.drawcoastlines`. If you need to
+#   use the underlying `~mpl_toolkits.basemap.Basemap` instance, it is
 #   available via the `proplot.axes.BasemapAxes.projection` attribute.
 #
 # Together, these features let you work with geophysical data without invoking
diff --git a/docs/subplots.py b/docs/subplots.py
@@ -227,10 +227,10 @@
 # Axis sharing
 # ------------
 #
-# Redundant labels are a common problem for figures with lots of subplots. To
-# address this, `matplotlib.pyplot.subplots` includes `sharex` and `sharey` keywords
-# that permit sharing axis limits, ticks, and tick labels between like rows and columns
-# of subplots. ProPlot expands upon this feature by:
+# :ref:`Redundant labels <why_redundant>` are a common problem for figures with lots of
+# subplots. To address this, `matplotlib.pyplot.subplots` includes `sharex` and `sharey`
+# keywords that permit sharing axis limits, ticks, and tick labels between like rows and
+# columns of subplots. ProPlot expands upon this feature by:
 
 # 1. Adding an option for sharing labels in the same row or column of the subplot grid,
 #    controlled by the `spanx` and `spany` keywords (default is :rc:`subplots.span`).
diff --git a/docs/why.rst b/docs/why.rst
