Update docs and order of appearence in API tables

Author: lukelbd

docs/1dplots.py

@@ -281,25 +281,24 @@
 # The `~matplotlib.axes.Axes.bar` and `~matplotlib.axes.Axes.barh` methods
 # are wrapped by `~proplot.axes.bar_extras`,
 # `~proplot.axes.apply_cycle`, and `~proplot.axes.standardize_1d`.
+# This means that `~matplotlib.axes.Axes.bar` and `~matplotlib.axes.Axes.barh` employ
+# default *x* or *y* coordinates if you failed to provide them explicitly.
 # You can now *group* or *stack* columns of data by passing 2D arrays to
 # `~matplotlib.axes.Axes.bar` or `~matplotlib.axes.Axes.barh`, just like in
-# `pandas`_, or use different colors for negative and positive bars by
-# passing ``negpos=True``. Also, `~matplotlib.axes.Axes.bar` and
-# `~matplotlib.axes.Axes.barh` now employ "default" *x* coordinates if you
-# failed to provide them explicitly.
+# `pandas`_. You can also use different colors for "negative" and "positive"
+# bars by passing ``negpos=True`` (the default colors are :rc:`negcolor`
+# and :rc:`poscolor`).
 #
-# To make filled "area" plots, use the new `~proplot.axes.Axes.area` and
-# `~proplot.axes.Axes.areax` methods. These are alises for
-# `~matplotlib.axes.Axes.fill_between` and
-# `~matplotlib.axes.Axes.fill_betweenx`, which are wrapped by
-# `~proplot.axes.fill_between_extras` and
-# `~proplot.axes.fill_betweenx_extras`. You can now *stack* or *overlay*
-# columns of data by passing 2D arrays to `~proplot.axes.Axes.area` and
-# `~proplot.axes.Axes.areax`, just like in `pandas`_. You can also now draw
-# area plots that change color when the fill boundaries cross each other by
-# passing ``negpos=True`` to `~matplotlib.axes.Axes.fill_between`. The most
-# common use case for this is highlighting negative and positive areas with
-# different colors, as shown below.
+# The `~matplotlib.axes.Axes.fill_between` and `~matplotlib.axes.Axes.fill_betweenx`
+# commands are wrapped by `~proplot.axes.fill_between_extras` and
+# `~proplot.axes.fill_betweenx_extras`. They also now have the optional shorthands
+# `~proplot.axes.Axes.area` and `~proplot.axes.Axes.areax`.
+# You can now *stack* or *overlay* columns of data by passing 2D arrays to
+# to these commands, just like in `pandas`_. You can also draw area plots that
+# change color when the fill boundaries cross each other by passing ``negpos=True``
+# (the default colors are :rc:`negcolor` and :rc:`poscolor`). The most common
+# use case for this is highlighting *negative* and *positive* areas with different
+# colors, as shown below.
 
 # %%
 import proplot as plot
@@ -400,12 +399,14 @@
 # --------------------------
 #
 # The `~matplotlib.axes.Axes.boxplot` and `~matplotlib.axes.Axes.violinplot`
-# methods are now wrapped with `~proplot.axes.boxplot_extras`,
+# commands are wrapped by `~proplot.axes.boxplot_extras`,
 # `~proplot.axes.violinplot_extras`, `~proplot.axes.apply_cycle`,
-# and `~proplot.axes.standardize_1d`. These wrappers add some useful
-# options and apply aesthetically pleasing default settings. They also
-# automatically apply axis labels based on the `~pandas.DataFrame` column
-# labels or the input *x* coordinate labels.
+# and `~proplot.axes.standardize_1d`. They also now have the optional shorthands
+# `~proplot.axes.Axes.boxes` and `~proplot.axes.Axes.violins`. The wrappers
+# apply aesthetically pleasing default settings and permit configuration using
+# keyword arguments like ``color``, ``boxcolor``, and ``fillcolor``. They also
+# automatically apply axis labels based on the `~pandas.DataFrame` or
+# `~xarray.DataArray` column labels or the input *x* coordinate labels.
 
 # %%
 import proplot as plot
@@ -443,90 +444,96 @@
 ax = axs[2]
 data = state.rand(100, 7)
 colors = plot.Colors('pastel2')  # list of colors from the cycle
-ax.boxes(data, fillcolor=colors)
+ax.boxplot(data, fillcolor=colors, orientation='horizontal')
 ax.format(title='Multiple colors', titleloc='uc', ymargin=0.15)
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
-# .. _ug_parametric:
+# .. _ug_lines:
 #
-# Parametric plots
-# ----------------
+# Line plots
+# ----------
 #
-# To make "parametric" plots, use the new `~proplot.axes.Axes.parametric`
-# method. Parametric plots are
-# `~matplotlib.collections.LineCollection`\ s that map individual line
-# segments to individual colors, where each segment represents a "parametric"
-# coordinate (e.g., time). The parametric coordinates are specified with the
-# `values` keyword argument. See `~proplot.axes.Axes.parametric` for details.
-# As shown below, it is also easy to build colorbars from the
-# `~matplotlib.collections.LineCollection` returned by
-# `~proplot.axes.Axes.parametric`.
+# The `~matplotlib.axes.Axes.plot` command is wrapped by
+# `~proplot.axes.apply_cycle` and `~proplot.axes.standardize_1d`.
+# But in general, its behavior is the same -- ProPlot simply tries to expand
+# the flexibility of this command to the rest of the 1D plotting commands.
+# The new `~proplot.axes.Axes.plotx` command can be used just like
+# `~matplotlib.axes.Axes.plotx`, except a single argument is interpreted
+# as *x* coordinates (with default *y* coordinates inferred from the data),
+# and multiple arguments are interpreted as *y* and *x* coordinates (in that order).
+# This is analogous to `~matplotlib.axes.Axes.barh` and
+# `~matplotlib.axes.Axes.fill_betweenx`.
+#
+# As with the other 1D plotting commands, `~matplotlib.axes.Axes.step`,
+# `~matplotlib.axes.Axes.hlines`, `~matplotlib.axes.Axes.vlines`, and
+# `~matplotlib.axes.Axes.stem` are wrapped by `~proplot.axes.standardize_1d`.
+# `~proplot.axes.Axes.step` now use the property cycle, just like
+# `~matplotlib.axes.Axes.plot`. `~matplotlib.axes.Axes.vlines` and
+# `~matplotlib.axes.Axes.hlines` are also wrapped by `~proplot.axes.vlines_extras`
+# and `~proplot.axes.hlines_extras`, which can use
+# different colors for "negative" and "positive" lines using ``negpos=True``
+# (the default colors are :rc:`negcolor` and :rc:`poscolor`).
 
 # %%
 import proplot as plot
 import numpy as np
-fig, axs = plot.subplots(
-    share=0, ncols=2, wratios=(2, 1),
-    figwidth='16cm', refaspect=(2, 1)
-)
-axs.format(suptitle='Parametric plots demo')
-cmap = 'IceFire'
-
-# Sample data
 state = np.random.RandomState(51423)
-N = 50
-x = (state.rand(N) - 0.52).cumsum()
-y = state.rand(N)
-c = np.linspace(-N / 2, N / 2, N)  # color values
+fig, axs = plot.subplots(ncols=2, nrows=2, share=0)
+axs.format(suptitle='Line plots demo', xlabel='xlabel', ylabel='ylabel')
 
-# Parametric line with smooth gradations
+# Step
 ax = axs[0]
-m = ax.parametric(
-    x, y, c, cmap=cmap, lw=7, interp=5, capstyle='round', joinstyle='round'
-)
-ax.format(xlabel='xlabel', ylabel='ylabel', title='Line with smooth gradations')
-ax.colorbar(m, loc='b', label='parametric coordinate', locator=5)
-
-# Sample data
-N = 12
-radii = np.linspace(1, 0.2, N + 1)
-angles = np.linspace(0, 4 * np.pi, N + 1)
-x = radii * np.cos(1.4 * angles)
-y = radii * np.sin(1.4 * angles)
-c = np.linspace(-N / 2, N / 2, N + 1)
+data = state.rand(20, 4).cumsum(axis=1).cumsum(axis=0)
+cycle = ('blue7', 'gray5', 'red7', 'gray5')
+ax.step(data, cycle=cycle, labels=list('ABCD'), legend='ul', legend_kw={'ncol': 2})
+ax.format(title='Step plot')
 
-# Parametric line with stepped gradations
+# Stems
 ax = axs[1]
-m = ax.parametric(x, y, c, cmap=cmap, lw=15)
-ax.format(
-    xlim=(-1, 1), ylim=(-1, 1), title='Step gradations',
-    xlabel='cosine angle', ylabel='sine angle'
-)
-ax.colorbar(m, loc='b', maxn=10, label='parametric coordinate')
+data = state.rand(20)
+ax.stem(data, linefmt='k-')
+ax.format(title='Stem plot')
 
+# Vertical lines
+gray = 'gray7'
+data = state.rand(20) - 0.5
+ax = axs[2]
+ax.area(data, color=gray, alpha=0.2)
+ax.vlines(data, negpos=True, linewidth=2)
+ax.format(title='Vertical lines')
+
+# Horizontal lines
+ax = axs[3]
+ax.areax(data, color=gray, alpha=0.2)
+ax.hlines(data, negpos=True, linewidth=2)
+ax.format(title='Horizontal lines')
 
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_scatter:
 #
-# Other plotting methods
-# ----------------------
+# Scatter plots
+# -------------
 #
-# The `~matplotlib.axes.Axes.scatter` method is now wrapped by
+# The `~matplotlib.axes.Axes.scatter` command is wrapped by
 # `~proplot.axes.scatter_extras`, `~proplot.axes.apply_cycle`, and
 # `~proplot.axes.standardize_1d`. This means that
-# `~matplotlib.axes.Axes.scatter` now accepts 2D arrays, just like
-# `~matplotlib.axes.Axes.plot`. Also, successive calls to
-# `~matplotlib.axes.Axes.scatter` now use the property cycler properties
-# (e.g.,  `color`, `marker`, and `markersize`), and
-# `~matplotlib.axes.Axes.scatter` now optionally accepts keywords that look
-# like `~matplotlib.axes.Axes.plot` keywords (e.g., `color` instead of `c` and
-# `markersize` instead of `s`).
+# `~matplotlib.axes.Axes.scatter` now accepts 2D *y* coordinates and permits
+# omitting *x* coordinates, just like `~matplotlib.axes.Axes.plot`.
+# `~matplotlib.axes.Axes.scatter` now also accepts keywords that look like
+# `~matplotlib.axes.Axes.plot` keywords (e.g., `color` instead of `c` and
+# `markersize` instead of `s`). This way, `~matplotlib.axes.Axes.scatter` can
+# optionally be used simply to "plot markers, not lines" without changing the
+# input arguments relative to `~matplotlib.axes.Axes.plot`.
 #
-# ProPlot also supports property cycling for `~proplot.axes.Axes.step` plots
-# and wraps the `~matplotlib.axes.Axes.vlines` and `~matplotlib.axes.Axes.hlines`
-# methods with `~proplot.axes.vlines_extras` and `~proplot.axes.hlines_extras`,
-# which adds the ability to use different colors for "negative" and "positive" lines.
+# Just like `~matplotlib.axes.Axes.plot`, the property cycle is used
+# with `~matplotlib.axes.Axes.scatter` plots by default. It can be changed
+# using the `cycle` keyword argument, and it can include properties like `marker`
+# and `markersize`. The colormap `cmap` and normalizer `norm` used with the
+# optional `c` color array are now passed through the `~proplot.constructor.Colormap`
+# and `~proplot.constructor.Norm` constructor functions, and the the `s` marker
+# size array can now be conveniently scaled using the arguments `smin` and `smax`
+# (analogous to `vmin` and `vmax` used for colors).
 
 # %%
 import proplot as plot
@@ -562,36 +569,58 @@
 )
 axs.format(xlabel='xlabel', ylabel='ylabel')
 
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_parametric:
+#
+# Parametric plots
+# ----------------
+#
+# To make "parametric" plots, use the new `~proplot.axes.Axes.parametric`
+# command. Parametric plots are `~matplotlib.collections.LineCollection`\ s that
+# map individual line segments to individual colors, where each segment represents a
+# "parametric" coordinate (e.g., time). The parametric coordinates are specified with
+# the `values` keyword argument. See `~proplot.axes.Axes.parametric` for details. As
+# shown below, it is also easy to build colorbars from the
+# `~matplotlib.collections.LineCollection` returned by `~proplot.axes.Axes.parametric`.
+
 # %%
 import proplot as plot
 import numpy as np
+fig, axs = plot.subplots(
+    share=0, ncols=2, wratios=(2, 1),
+    figwidth='16cm', refaspect=(2, 1)
+)
+axs.format(suptitle='Parametric plots demo')
+cmap = 'IceFire'
+
+# Sample data
 state = np.random.RandomState(51423)
-fig, axs = plot.subplots(ncols=2, nrows=2, share=0)
-axs.format(suptitle='Line plots demo', xlabel='xlabel', ylabel='ylabel')
+N = 50
+x = (state.rand(N) - 0.52).cumsum()
+y = state.rand(N)
+c = np.linspace(-N / 2, N / 2, N)  # color values
 
-# Step
+# Parametric line with smooth gradations
 ax = axs[0]
-data = state.rand(20, 4).cumsum(axis=1).cumsum(axis=0)
-cycle = ('blue7', 'gray5', 'red7', 'gray5')
-ax.step(data, cycle=cycle, labels=list('ABCD'), legend='ul', legend_kw={'ncol': 2})
-ax.format(title='Step plot')
-
-# Stems
-ax = axs[1]
-data = state.rand(20)
-ax.stem(data, linefmt='k-')
-ax.format(title='Stem plot')
+m = ax.parametric(
+    x, y, c, cmap=cmap, lw=7, interp=5, capstyle='round', joinstyle='round'
+)
+ax.format(xlabel='xlabel', ylabel='ylabel', title='Line with smooth gradations')
+ax.colorbar(m, loc='b', label='parametric coordinate', locator=5)
 
-# Vertical lines
-gray = 'gray7'
-data = state.rand(20) - 0.5
-ax = axs[2]
-ax.area(data, color=gray, alpha=0.2)
-ax.vlines(data, negpos=True, linewidth=2)
-ax.format(title='Vertical lines')
+# Sample data
+N = 12
+radii = np.linspace(1, 0.2, N + 1)
+angles = np.linspace(0, 4 * np.pi, N + 1)
+x = radii * np.cos(1.4 * angles)
+y = radii * np.sin(1.4 * angles)
+c = np.linspace(-N / 2, N / 2, N + 1)
 
-# Horizontal lines
-ax = axs[3]
-ax.areax(data, color=gray, alpha=0.2)
-ax.hlines(data, negpos=True, linewidth=2)
-ax.format(title='Horizontal lines')
+# Parametric line with stepped gradations
+ax = axs[1]
+m = ax.parametric(x, y, c, cmap=cmap, lw=15)
+ax.format(
+    xlim=(-1, 1), ylim=(-1, 1), title='Step gradations',
+    xlabel='cosine angle', ylabel='sine angle'
+)
+ax.colorbar(m, loc='b', maxn=10, label='parametric coordinate')

docs/_static/custom.css

@@ -77,17 +77,14 @@
   --accent-bg-color: #505050;
 }
 
-/* Font families from modern pydata theme */
-/* Github fonts: */
-/* font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; */
-/* Pandas fonts: */
-/* -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; */
-/* SFMono-Regular, Menlo, Consolas, Monaco, "Liberation Mono", "Lucida Console", monospace; */
+/* Pydata theme font families */
+/* Github: font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; */
+/* Pandas: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; */
 body, h1, h2, h3, h4, h5, h6, .rst-content .toctree-wrapper p.caption{
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
 }
 
-
+/* Readjust font sizes */
 /* Keep bold headers but slightly larger than RTD and smaller than pydata */
 .rst-content div[class^='highlight'] pre,
 .rst-content pre.literal-block,

docs/api.rst

@@ -2,6 +2,10 @@
 API reference
 =============
 
+Comprehensive documentation of ProPlot functions and classes. Since all of
+these objects are imported into the top-level namespace, you can read the
+documentation within python sessions using ``help(plot.<function_or_class>)``.
+
 Top-level functions
 ===================
 

docs/basics.py

@@ -49,24 +49,32 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. note::
 #
-#    ProPlot figure backgrounds are only gray when displayed by the
-#    `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.
-#
-#    ProPlot also changes the default :rcraw:`savefig.format` from PNG to PDF for the
-#    following reasons:
+#    ProPlot changes the default :rcraw:`figure.facecolor` so that the figure
+#    backgrounds shown by the `matplotlib backend\
+#    <https://matplotlib.org/faq/usage_faq#what-is-a-backend>`__ are gray (the
+#    :rcraw:`savefig.facecolor` applied to saved figures is still white). This can be
+#    helpful when designing figures. ProPlot also controls the appearence of figures
+#    in Jupyter notebooks using the new :rcraw:`inlinefmt` setting, which is passed
+#    to `~proplot.config.config_inline_backend` on import. This imposes a
+#    higher-quality default `"inline" format\
+#    <https://ipython.readthedocs.io/en/stable/interactive/plotting.html>`__
+#    and disables the backend-specific settings ``InlineBackend.rc`` and
+#    ``InlineBackend.print_figure_kwargs``, ensuring that the figures you save
+#    look identical to the figures displayed by the backend.
+#
+#    ProPlot also changes the default :rcraw:`savefig.format` from PNG to
+#    PDF for the following reasons:
 #
 #        #. Vector graphic formats are infinitely scalable.
 #        #. Vector graphic formats are preferred by academic journals.
-#        #. Most academic journals accept PDF figures alongside the traditional
-#           `EPS <https://en.wikipedia.org/wiki/Encapsulated_PostScript>`__ format.
-#        #. The EPS format does not support transparent graphic elements.
-#
-#    In case you *do* need raster graphics, ProPlot sets the default
-#    :rcraw:`savefig.dpi` to 1000 dots per inch, which is
-#    `recommended by most journals <https://www.pnas.org/page/authors/format>`__
+#        #. Nearly all academic journals accept figures in the PDF format alongside
+#           the `EPS <https://en.wikipedia.org/wiki/Encapsulated_PostScript>`__ format.
+#        #. The EPS format is outdated and does not support transparent graphic
+#           elements.
+#
+#    In case you *do* need a raster format like PNG, ProPlot increases the
+#    default :rcraw:`savefig.dpi` to 1000 dots per inch, which is
+#    `recommended <https://www.pnas.org/page/authors/format>`__ by most journals
 #    as the minimum resolution for rasterized figures containing lines and text.
 #    See the :ref:`configuration section <ug_proplotrc>` for how to change
 #    these settings.
@@ -77,8 +85,8 @@
 #    column share the same axis limits, scales, ticks, and labels. This is often
 #    convenient, but may be annoying for some users. To keep this feature turned off,
 #    simply :ref:`change the default settings <ug_rc>` with e.g.
-#    ``plot.rc.update(share=False, span=False)``. See :ref:`this section <ug_share>`
-#    for details.
+#    ``plot.rc.update(share=False, span=False)``. See the
+#    :ref:`axis-sharing section <ug_share>` for details.
 
 # %%
 # Sample data