Update docs

Author: lukelbd

WHATSNEW.rst

@@ -79,7 +79,7 @@ ProPlot v0.7.1 (2021-##-##)
 * Fix issue where deprecated `aspect` `~proplot.ui.subplots` argument
   is ignored (:commit:`70a8b87d`).
 * Fix issue where `~proplot.axes.Axes.parametric` ignores `interp` when
-  selecting default colormap levels (:commit:`152a3a81`).
+  selecting `DiscreteNorm` colormap levels (:commit:`152a3a81`).
 * Fix issue where a-b-c labels are removed in presence of ``'top'`` panels
   with ``titleabove=True`` (:commit:`7873d5e0`).
 * Ensure `plot` returns tuples of handles instead of lists, and ensure `indicate_error`
@@ -94,6 +94,20 @@ ProPlot v0.7.1 (2021-##-##)
   default row label rotation match default y label rotation (:commit:`bae85113`).
 * Make `~proplot.axes.colorbar_extras` capture matplotlib-native `format` keyword
   as alias for `formatter` and `ticklabels` (:issue:`262`).
+* Permit legends from mappables using ``ContourSet.legend_elements``
+  and ``Collection.legend_elements`` (:pr:`264`).
+* Add `stepx` command analogous to `plotx` and `histh`, `boxploth`, and `violinploth`
+  commands analogous to `barh` (:pr:`264`). Also add aliases.
+
+.. rubric:: Internals
+
+* Convert all plotting wrappers to dedicated overrides of individual functions
+  (:pr:`264`). This massively simplifies the internals and makes learning
+  and adopting proplot much easier for new users.
+* Use metaclasses to redirect internal plotting calls to native matplotlib
+  methods (:pr:`264`). Much safer/more stable this way.
+* Use metaclasses to efficiently impose defaults ``latlon=True`` and
+  ``transform=PlateCarree()`` in 90% fewer lines (:pr:`264`).
 
 
 ProPlot v0.7.0 (2021-07-11)

docs/api.rst

@@ -31,7 +31,6 @@ Axes classes
 
 .. automodsumm:: proplot.axes
    :toctree: api
-   :classes-only:
 
 
 Constructor functions
@@ -52,16 +51,6 @@ Configuration tools
    :skip: inline_backend_fmt
 
 
-Plotting wrappers
-=================
-
-.. automodule:: proplot.axes.plot
-
-.. automodsumm:: proplot.axes
-   :toctree: api
-   :functions-only:
-
-
 Demo functions
 ==============
 

docs/basics.py

@@ -276,8 +276,8 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_container:
 #
-# Subplot containers
-# ------------------
+# Multiple axes
+# -------------
 #
 # `matplotlib.pyplot.subplots` returns a 2D `~numpy.ndarray` for figures with more
 # than one column and row, a 1D `~numpy.ndarray` for single-column or row figures,
@@ -306,13 +306,15 @@
 import proplot as pplt
 import numpy as np
 state = np.random.RandomState(51423)
+
+# Format all subplots at once
 fig, axs = pplt.subplots(ncols=4, nrows=4, refwidth=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
+# Format selected 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)

docs/colormaps.py

@@ -188,13 +188,15 @@
 # ``'hpl'`` colorspaces.
 
 # %%
+# Sample data
 import proplot as pplt
 import numpy as np
 state = np.random.RandomState(51423)
 data = state.rand(30, 30).cumsum(axis=1)
 
-# Initialize figure
-fig, axs = pplt.subplots(ncols=2, nrows=2, refwidth=2, span=0)
+# %%
+# Create figure
+fig, axs = pplt.subplots(ncols=2, refwidth=2, span=0)
 axs.format(
     xticklabels='none',
     yticklabels='none',
@@ -216,11 +218,23 @@
 m = ax.contourf(data, cmap=cmap2)
 ax.colorbar(m, loc='b', ticks='none', label=cmap2.name)
 
+# Display the channels
+fig, axs = pplt.show_channels(cmap1, cmap2, refwidth=1.5, rgb=False)
+
+# %%
+# Create figure
+fig, axs = pplt.subplots(ncols=2, refwidth=2, span=0)
+axs.format(
+    xticklabels='none',
+    yticklabels='none',
+    suptitle='Making PerceptuallyUniformColormaps'
+)
+
 # Sequential colormap from channel values
 cmap3 = pplt.Colormap(
     h=('red', 'red-720'), s=(80, 20), l=(20, 100), space='hpl', name='CubeHelix'
 )
-ax = axs[2]
+ax = axs[0]
 ax.format(title='Sequential from channel values')
 m = ax.contourf(data, cmap=cmap3)
 ax.colorbar(m, loc='b', ticks='none', label=cmap3.name)
@@ -229,13 +243,12 @@
 cmap4 = pplt.Colormap(
     h=(0, 360), c=50, l=70, space='hcl', cyclic=True, name='Spectrum'
 )
-ax = axs[3]
+ax = axs[1]
 ax.format(title='Cyclic from channel values')
 m = ax.contourf(data, cmap=cmap4)
 ax.colorbar(m, loc='b', ticks='none', label=cmap4.name)
 
 # Display the channels
-fig, axs = pplt.show_channels(cmap1, cmap2, refwidth=1.5, rgb=False)
 fig, axs = pplt.show_channels(cmap3, cmap4, refwidth=1.5, rgb=False)
 
 
@@ -376,7 +389,7 @@
 state = np.random.RandomState(51423)
 data = (state.rand(40, 40) - 0.5).cumsum(axis=0).cumsum(axis=1)
 
-# Generate figure
+# Create figure
 fig, axs = pplt.subplots(ncols=2, nrows=2, refwidth=1.7, span=False)
 axs.format(
     xlabel='x axis', ylabel='y axis', xticklabels='none',

docs/projections.py

@@ -31,68 +31,13 @@
 # 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
-# with the subplot number as the key -- for example, ``proj={1: 'name'}``. The *default*
-# projection is always `~proplot.axes.CartesianAxes` (it can be explicitly specified
-# with ``proj='cartesian'``).
-
-# %% [raw] raw_mimetype="text/restructuredtext"
-# .. _ug_polar:
-#
-# Polar axes
-# ----------
-#
-# To draw `polar axes <polar_>`_, pass ``proj='polar'`` or e.g. ``proj={1: 'polar'}``
-# to `~proplot.ui.subplots`. This generates a `proplot.axes.PolarAxes` instance with
-# its own `~proplot.axes.PolarAxes.format` method.
-#
-# The `proplot.axes.PolarAxes.format` method facilitates polar-specific axes
-# modifications like changing the central radius `r0`, the zero azimuth location
-# `theta0`, and the positive azimuthal direction `thetadir`. It also supports
-# changing gridline locations with `rlocator` and `thetalocator` (analogous to
-# `ylocator` and `xlocator` used by `~proplot.axes.CartesianAxes.format`) and
-# turning your polar plot into an "annular" or "sector" plot by changing the radial
-# limits `rlim` or the azimuthal limits `thetalim`. Finally, since
-# `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`.
-
-# %%
-import proplot as pplt
-import numpy as np
-N = 200
-state = np.random.RandomState(51423)
-x = np.linspace(0, 2 * np.pi, N)
-y = 100 * (state.rand(N, 5) - 0.3).cumsum(axis=0) / N
-fig, axs = pplt.subplots([[1, 1, 2, 2], [0, 3, 3, 0]], proj='polar')
-axs.format(
-    suptitle='Polar axes demo', linewidth=1, titlepad='1em',
-    ticklabelsize=9, rlines=0.5, rlim=(0, 19),
-)
-for i in range(5):
-    xi = x + i * 2 * np.pi / 5
-    axs.plot(xi, y[:, i], cycle='FlatUI', zorder=0, lw=3)
-
-# Standard polar plot
-axs[0].format(
-    title='Normal plot', thetaformatter='tau',
-    rlabelpos=225, rlines=pplt.arange(5, 30, 5),
-    color='red8', tickpad='1em',
-)
-
-# Sector plot
-axs[1].format(
-    title='Sector plot', thetadir=-1, thetalines=90, thetalim=(0, 270), theta0='N',
-    rlim=(0, 22), rlines=pplt.arange(5, 30, 5),
-)
-
-# Annular plot
-axs[2].format(
-    title='Annular plot', thetadir=-1, thetalines=20, gridcolor='red',
-    r0=-20, rlim=(0, 22), rformatter='null', rlocator=2
-)
+# different projections for different subplots, pass a list of projection names or
+# a dictionary of projection names with the subplot number as the key -- for example,
+# a 2-column figure with a Cartesian axes on the left and a Plate Carrée projection
+# on the right can be built with either ``proj=('cartesian', 'pcarree')`` or
+# ``proj={2: 'pcarree'}``. The *default* projection is always
+# `~proplot.axes.CartesianAxes` and can be explicitly specified with
+# the ``'cartesian'`` key.
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -177,14 +122,12 @@
 #    Basemap is `no longer maintained \
 #    <https://matplotlib.org/basemap/users/intro.html#cartopy-new-management-and-eol-announcement>`__
 #    and will not work with matplotlib versions more recent than 3.2.2. However, as
-#    shown below, gridline labels tend to look nicer in basemap
-#    than in cartopy -- especially when "inline" cartopy labels are disabled.
-#    This is the main reason ProPlot continues to support both basemap and cartopy.
-#    When cartopy's gridline labels improve, basemap support may be deprecated.
+#    shown below, gridline labels often look nicer in basemap than cartopy --
+#    especially when "inline" cartopy labels are disabled. This is the main reason
+#    ProPlot supports both basemap and cartopy. When cartopy gridline labels
+#    improve, basemap support may be deprecated.
 
 # %%
-# Simple figure with just one projection
-
 # Option 1: Create a projection manually with pplt.Proj()
 # immport proplot as plot
 # proj = pplt.Proj('robin', lon_0=180)
@@ -233,10 +176,10 @@
 # just like cartopy. When using basemap as the "backend", you should not have to work
 # with the `~mpl_toolkits.basemap.Basemap` instance directly.
 #
-# To ensure the graphics generated by :ref:`2D plotting commands <ug_2dplots>` like
+# To ensure the graphics generated by :ref:`plotting commands <ug_2dplots>` like
 # `~matplotlib.axes.Axes.contour` fill the entire globe, simply pass ``globe=True`` to
-# the plotting command. This interpolates your data to the poles and across the
-# longitude seam before plotting the data. This is a convenient alternative to
+# the plotting command. This interpolates the data to the poles and across the
+# longitude seam before plotting. This is a convenient alternative to
 # cartopy's `~cartopy.util.add_cyclic_point` and basemap's
 # `~mpl_toolkits.basemap.addcyclic`.
 #
@@ -479,3 +422,62 @@
 )
 for proj, ax in zip(projs, axs):
     ax.format(title=proj, titleweight='bold', labels=False)
+
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_polar:
+#
+# Polar axes
+# ----------
+#
+# To draw `polar axes <polar_>`_, pass ``proj='polar'`` or e.g. ``proj={1: 'polar'}``
+# to `~proplot.ui.subplots`. This generates a `proplot.axes.PolarAxes` instance with
+# its own `~proplot.axes.PolarAxes.format` method.
+#
+# The `proplot.axes.PolarAxes.format` method facilitates polar-specific axes
+# modifications like changing the central radius `r0`, the zero azimuth location
+# `theta0`, and the positive azimuthal direction `thetadir`. It also supports
+# changing gridline locations with `rlocator` and `thetalocator` (analogous to
+# `ylocator` and `xlocator` used by `~proplot.axes.CartesianAxes.format`) and
+# turning your polar plot into an "annular" or "sector" plot by changing the radial
+# limits `rlim` or the azimuthal limits `thetalim`. Finally, since
+# `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`.
+
+# %%
+import proplot as pplt
+import numpy as np
+N = 200
+state = np.random.RandomState(51423)
+x = np.linspace(0, 2 * np.pi, N)
+y = 100 * (state.rand(N, 5) - 0.3).cumsum(axis=0) / N
+fig, axs = pplt.subplots([[1, 1, 2, 2], [0, 3, 3, 0]], proj='polar')
+axs.format(
+    suptitle='Polar axes demo', linewidth=1, titlepad='1em',
+    ticklabelsize=9, rlines=0.5, rlim=(0, 19),
+)
+for i in range(5):
+    xi = x + i * 2 * np.pi / 5
+    axs.plot(xi, y[:, i], cycle='FlatUI', zorder=0, lw=3)
+
+# Standard polar plot
+axs[0].format(
+    title='Normal plot', thetaformatter='tau',
+    rlabelpos=225, rlines=pplt.arange(5, 30, 5),
+    color='red8', tickpad='1em',
+)
+
+# Sector plot
+axs[1].format(
+    title='Sector plot', thetadir=-1, thetalines=90, thetalim=(0, 270), theta0='N',
+    rlim=(0, 22), rlines=pplt.arange(5, 30, 5),
+)
+
+# Annular plot
+axs[2].format(
+    title='Annular plot', thetadir=-1, thetalines=20, gridcolor='red',
+    r0=-20, rlim=(0, 22), rformatter='null', rlocator=2
+)

docs/subplots.py

@@ -85,7 +85,7 @@
 # Automatic sizing
 # ----------------
 #
-# By default, ProPlot determines the suitable figure size given
+# ProPlot by default determines the suitable figure size given
 # the geometry of your subplot grid and the size of a "reference"
 # subplot. ProPlot can also determine the suitable figure height given a
 # fixed *figure* width, and figure width given a fixed *figure* height.