Clean up docs

Author: lukelbd

WHATSNEW.rst

@@ -348,38 +348,39 @@ ProPlot v0.6.0 (2020-05-20)
 * Drop support for ``.rgba`` files, but optionally read 4th opacity column
   from ``.rgb`` and ``.txt`` files (:commit:`4fa72b0c`).
 * Stop reversing the ``'Spectral'`` colormap when ProPlot is imported
-  (:commit:`ce4ef6a0`).
-* Remove ``'Blue0'`` SciVisColor colormap (:commit:`7cb4ce0f`). It was odd man
-  out in the table, and not even really perceptually uniform.
+  (:pr:`149`, :commit:`ce4ef6a0`).
+* Remove ``'Blue0'`` SciVisColor colormap (:pr:`149`, :commit:`7cb4ce0f`). It was odd
+  man out in the table, and not even really perceptually uniform.
 * Remove custom ProPlot cycles -- these should be thought out much more
   carefully (:commit:`43f65d17`).
-* Remove "crayola" colors and clean up the `~proplot.setup.register_colors`
-  algorithm (:commit:`8922d6de`). Crayola color names less intuitive than XKCD.
+* Remove "crayola" colors and clean up the `~proplot.setup.register_colors` algorithm
+  (:pr:`149`, :commit:`8922d6de`). Crayola color names less intuitive than XKCD.
 * Use ``'cmap_s'`` instead of ``'cmap_shifted'`` to quickly get a 180
-  degree-shifted colormap, similar to ``'cmap_r'`` (:commit:`da4ccb08`).
+  degree-shifted colormap, similar to ``'cmap_r'`` (:pr:`149`, :commit:`da4ccb08`).
 * Rename ``GrayCycle`` colormap to ``MonoCycle`` to more accurately reflect
-  colormap design origins (:commit:`d67e45bf`).
-* Rename `~proplot.config.rc_configurator` to `~proplot.config.RcConfigurator`
-  to match capitalized class naming convention.
+  colormap design origins (:pr:`149`, :commit:`d67e45bf`).
+* Rename `~proplot.config.rc_configurator` and `~proplot.ui.subplot_grid` to
+  `~proplot.config.RcConfigurator` and `~proplot.ui.SubplotsContainer`
+  to match capitalized class naming convention (:pr:`149`).
 * Rename `~proplot.colors.MidpointNorm` to more intuitive
   `~proplot.colors.DivergingNorm`, and make "fair" color scaling the default
   behavior (:commit:`2f549c9`).
 * Rename `XYAxes` to `~proplot.axes.CartesianAxes`, `~proplot.axes.GeoAxes`
   to `~proplot.axes.CartopyAxes`, and `~proplot.axes.ProjAxes` to
-  `~proplot.axes.GeoAxes` (:commit:`4a6a0e34`).
+  `~proplot.axes.GeoAxes` (:pr:`149`, :commit:`4a6a0e34`).
 * Rename `BinNorm` to `~proplot.styletools.DiscreteNorm`
-  and fix issues with diverging norm color scaling (:commit:`98a976f1`).
+  and fix issues with diverging norm color scaling (:pr:`149`, :commit:`98a976f1`).
 * Rename `ColorDict` to `~proplot.colors.ColorDatabase`, `CmapDict`
-  to `~proplot.colors.ColormapDatabase` (:commit:`9d7fd3e0`).
+  to `~proplot.colors.ColormapDatabase` (:pr:`149`, :commit:`9d7fd3e0`).
 * Rename `~proplot.styletools.LinearSegmentedColormap.concatenate` to
   `~proplot.styletools.LinearSegmentedColormap.append`,
   `~proplot.styletools.LinearSegmentedColormap.updated` to
   `~proplot.styletools.LinearSegmentedColormap.copy`,
   `~proplot.styletools.LinearSegmentedColormap.truncated` to
   `~proplot.styletools.LinearSegmentedColormap.truncate`, and
   `~proplot.styletools.LinearSegmentedColormap.punched` to
-  `~proplot.styletools.LinearSegmentedColormap.cut` (:commit:`e1a08930`).  The old
-  method names remain with a deprecation warning.
+  `~proplot.styletools.LinearSegmentedColormap.cut` (:pr:`149`, :commit:`e1a08930`).
+  The old method names remain with a deprecation warning.
 
 .. rubric:: Features
 

docs/1dplots.py

@@ -525,8 +525,8 @@
 data = state.rand(2, 100)
 obj = ax.scatter(
     *data, color=data.sum(axis=0), size=state.rand(100), smin=3, smax=30,
-    marker='o', cmap='dark red', colorbar='lr', vmin=0, vmax=2,
-    colorbar_kw={'label': 'label', 'locator': 0.5}
+    marker='o', cmap='dark red', cmap_kw={'fade': 90}, vmin=0, vmax=2,
+    colorbar='lr', colorbar_kw={'label': 'label', 'locator': 0.5},
 )
 axs.format(xlabel='xlabel', ylabel='ylabel')
 

docs/2dplots.py

@@ -42,7 +42,7 @@
 # are passed to `~proplot.constructor.Colormap` and the resulting colormap is
 # used for the plot. For example, to create and apply a monochromatic colormap,
 # you can simply use ``cmap='color name'``.
-
+#
 # The `~proplot.axes.cmap_changer` wrapper also
 # adds the `norm` and `norm_kw` arguments. They are passed to the
 # `~proplot.constructor.Norm` constructor function, and the resulting

docs/basics.py

@@ -28,13 +28,12 @@
 # ProPlot works by creating a `proplot.figure.Figure` subclass of the
 # matplotlib figure class `~matplotlib.figure.Figure`, and a `proplot.axes.Axes`
 # subclass of the matplotlib axes class `~matplotlib.axes.Axes`.
-# All plotting in ProPlot begins by generating
-# an instance of the new figure class filled with instances of the new
-# axes classes using the `~proplot.ui.subplots` command, which is modeled
-# after `matplotlib.pyplot.subplots`.
-# ProPlot's `~proplot.ui.subplots` command can be used as follows:
 #
-# * Without any arguments, `~proplot.ui.subplots` returns a figure with a
+# The `~proplot.ui.subplots` command is used to create ProPlot figures. Modeled after
+# `matplotlib.pyplot.subplots`, it generates a `proplot.figure.Figure` instance filled
+# with `proplot.axes.Axes` instances. `~proplot.ui.subplots` can be used as follows:
+#
+# * With no arguments, `~proplot.ui.subplots` returns a figure with a
 #   single subplot.
 # * With `ncols` or `nrows`, `~proplot.ui.subplots` returns a
 #   figure with a simple grid of subplots.
@@ -44,9 +43,8 @@
 #   `~matplotlib.gridspec.GridSpec` slot that is occupied by the corresponding
 #   subplot and ``0`` indicates an empty space.
 #
-# In the below examples, we create subplot grids with `~proplot.ui.subplots`
-# and modify the axes labels. See the :ref:`formatting guide <ug_format>`
-# and :ref:`subplots container <ug_container>` sections for details.
+# In the below examples, we create a few simple figures with `~proplot.ui.subplots`.
+# See the next sections for details.
 
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. note::
@@ -55,7 +53,9 @@
 #    `matplotlib backend <https://matplotlib.org/faq/usage_faq#what-is-a-backend>`__
 #    -- the default background color is white when the figure is saved. This is done
 #    by setting :rcraw:`figure.facecolor` to gray, in order to improve contrast
-#    when working with figures, similar to MATLAB. ProPlot also changes the default
+#    when working with figures, similar to MATLAB.
+#
+#    ProPlot also changes the default
 #    :rcraw:`savefig.format` from PNG to PDF for the following reasons:
 #
 #        #. Vector graphic formats are infinitely scalable.
@@ -132,26 +132,24 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_plots:
 #
-# Plotting data
-# -------------
+# Plotting stuff
+# --------------
 #
 # Matplotlib has
-# `two different APIs <https://matplotlib.org/3.2.1/api/index.html>`__:
-# an object-oriented API and a MATLAB-style
-# `~matplotlib.pyplot` API (which uses the object-oriented API internally).
-# Plotting in ProPlot is just like plotting in matplotlib with
-# the *object-oriented* API. Rather than creating
-# a brand new interface, ProPlot simply builds upon the existing matplotlib
-# constructs of the `~matplotlib.axes.Axes` and the `~matplotlib.figure.Figure`
-# by adding new commands and new options to existing commands, without changing
-# the usage or syntax. This means a shallow learning curve for the average
-# matplotlib user.
+# `two different interfaces <https://matplotlib.org/3.2.1/api/index.html>`__:
+# an object-oriented interface and a MATLAB-style `~matplotlib.pyplot` interface
+# (which uses the object-oriented interface internally). Plotting with ProPlot is
+# just like plotting with matplotlib's *object-oriented* interface. Proplot builds
+# upon the matplotlib constructs of the `~matplotlib.figure.Figure` and the
+# `~matplotlib.axes.Axes` by adding new commands and adding new features to
+# existing commands. These additions do not change the usage or syntax of existing
+# commands, which means a shallow learning curve for the average matplotlib user.
 #
 # In the below example, we create a 4-panel figure with the familiar matplotlib
 # commands `~matplotlib.axes.Axes.plot`, `~matplotlib.axes.Axes.scatter`,
 # `~matplotlib.axes.Axes.pcolormesh`, and `~matplotlib.axes.Axes.contourf`.
 # See the :ref:`1d plotting <ug_1dplots>` and :ref:`2d plotting <ug_2dplots>`
-# sections for details on the plotting features added by ProPlot.
+# sections for details on the features added by ProPlot.
 
 
 # %%
@@ -176,7 +174,7 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_format:
 #
-# Formatting plots
+# Formatting stuff
 # ----------------
 #
 # Every `~matplotlib.axes.Axes` returned by `~proplot.ui.subplots` has a
@@ -191,7 +189,7 @@
 #    `proplot.axes.CartesianAxes.format`, `proplot.axes.PolarAxes.format`, or
 #    `proplot.axes.GeoAxes.format`. These change settings that are
 #    specific to the axes type. For example:
-
+#
 #    * To change the *x* axis bounds on a `~proplot.axes.CartesianAxes`,
 #      use e.g. ``xlim=(0, 5)``.
 #    * To change the radial bounds on a `~proplot.axes.PolarAxes`, use e.g.
@@ -242,12 +240,49 @@
     xtickdir='inout', xtickminor=False, ygridminor=True,
 )
 
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_container:
+#
+# Formatting all-at-once
+# ----------------------
+#
+# Instead of an `~numpy.ndarray` of subplots, `~proplot.ui.subplots` returns a
+# `~proplot.ui.SubplotsContainer`. This container behaves like an
+# `~matplotlib.axes.Axes` object when it contains just one axes, and behaves
+# like a list otherwise. It supports both 1D indexing (e.g. ``axs[1]``) and
+# 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.
+
+# %%
+import proplot as plot
+import numpy as np
+state = np.random.RandomState(51423)
+fig, axs = plot.subplots(ncols=4, nrows=4, axwidth=1.2)
+axs.format(
+    xlabel='xlabel', ylabel='ylabel', suptitle='SubplotsContainer demo',
+    grid=False, xlim=(0, 50), ylim=(-4, 4)
+)
+
+# Various ways to select subplots in the container
+axs[:, 0].format(facecolor='blush', color='gray7', linewidth=1)
+axs[0, :].format(facecolor='sky blue', color='gray7', linewidth=1)
+axs[0].format(color='black', facecolor='gray5', linewidth=1.4)
+axs[1:, 1:].format(facecolor='gray1')
+for ax in axs[1:, 1:]:
+    ax.plot((state.rand(50, 5) - 0.5).cumsum(axis=0), cycle='Grays', lw=2)
+
 
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_rc:
 #
-# Changing rc settings
-# --------------------
+# Styles and settings
+# -------------------
 #
 # A special object named `~proplot.config.rc` is created whenever you import
 # ProPlot. `~proplot.config.rc` is similar to the matplotlib
@@ -326,41 +361,3 @@
 for ax, style in zip(axs, styles):
     ax.format(style=style, xlabel='xlabel', ylabel='ylabel', title=style)
     ax.plot(data, linewidth=3)
-
-
-# %% [raw] raw_mimetype="text/restructuredtext"
-# .. _ug_container:
-#
-# Subplots containers
-# -------------------
-#
-# Instead of an `~numpy.ndarray` of axes, `~proplot.ui.subplots` returns a
-# `~proplot.ui.SubplotsContainer` instance. This container behaves like an
-# `~matplotlib.axes.Axes` object when it contains just one axes, and behaves
-# like a list otherwise. It supports both 1D indexing (e.g. ``axs[1]``) and
-# 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]``),
-# and `~proplot.axes.Axes` methods can be called simultaneously for all axes in the
-# container by calling the method from the container (e.g. ``axs.format(abc=True)``).
-#
-# In the below example, the `~proplot.ui.SubplotsContainer` returned by
-# `~proplot.ui.subplots` is used to cusomtize several axes at once with
-# `proplot.axes.Axes.format`.
-
-# %%
-import proplot as plot
-import numpy as np
-state = np.random.RandomState(51423)
-fig, axs = plot.subplots(ncols=4, nrows=4, axwidth=1.2)
-axs.format(
-    xlabel='xlabel', ylabel='ylabel', suptitle='SubplotsContainer demo',
-    grid=False, xlim=(0, 50), ylim=(-4, 4)
-)
-
-# Various ways to select subplots in the container
-axs[:, 0].format(facecolor='blush', color='gray7', linewidth=1)
-axs[0, :].format(facecolor='sky blue', color='gray7', linewidth=1)
-axs[0].format(color='black', facecolor='gray5', linewidth=1.4)
-axs[1:, 1:].format(facecolor='gray1')
-for ax in axs[1:, 1:]:
-    ax.plot((state.rand(50, 5) - 0.5).cumsum(axis=0), cycle='Grays', lw=2)

docs/configuration.rst

@@ -34,7 +34,7 @@ to the `~proplot.axes.Axes.format` command:
   ax.format(rc_kw={'name1': value1, 'name2': value2})
 
 To temporarily modify settings for particular figure(s), pass the setting
-to the `~proplot.config.rc_configurator.context` command:
+to the `~proplot.config.RcConfigurator.context` command:
 
 .. code-block:: python
 

docs/projections.py

@@ -6,7 +6,7 @@
 #       extension: .py
 #       format_name: percent
 #       format_version: '1.3'
-#       jupytext_version: 1.4.2
+#       jupytext_version: 1.3.0
 #   kernelspec:
 #     display_name: Python 3
 #     language: python
@@ -16,9 +16,9 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 #
 # .. _polar: https://matplotlib.org/3.1.0/gallery/pie_and_polar_charts/polar_demo.html
-
+#
 # .. _cartopy: https://scitools.org.uk/cartopy/docs/latest/
-
+#
 # .. _basemap: https://matplotlib.org/basemap/index.html
 #
 # .. _ug_proj:
@@ -206,8 +206,8 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_geoplot:
 #
-# Plotting geographic data
-# ------------------------
+# Geographic plotting
+# -------------------
 #
 # In ProPlot, plotting in `~proplot.axes.GeoAxes` is not much different from
 # plotting in `~proplot.axes.CartesianAxes`. ProPlot makes longitude-latitude