More docs cleanup

lukelbd · lukelbd · commit 246ffde6bb19 · 2020-05-06T20:32:45.000-06:00
diff --git a/docs/2dplots.py b/docs/2dplots.py
@@ -198,7 +198,7 @@
     ('fair', 'unfair')
 ):
     for fair in ('fair', 'unfair'):
-        norm = plot.Norm('diverging', unfair=(fair == 'unfair'))
+        norm = plot.Norm('diverging', fair=(fair == 'fair'))
         ax = axs[i]
         m = ax.contourf(data, cmap=cmap, norm=norm)
         ax.colorbar(m, loc='b', locator=1)
diff --git a/docs/colormaps.py b/docs/colormaps.py
@@ -72,7 +72,7 @@
 
 # %%
 import proplot as plot
-fig = plot.show_cmaps()
+fig, axs = plot.show_cmaps()
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -118,10 +118,10 @@
 
 # %%
 import proplot as plot
-fig = plot.show_colorspaces(axwidth=1.6, luminance=50)
-fig = plot.show_colorspaces(axwidth=1.6, saturation=60)
-fig = plot.show_colorspaces(axwidth=1.6, hue=0)
-fig = plot.show_channels(
+fig, axs = plot.show_colorspaces(axwidth=1.6, luminance=50)
+fig, axs = plot.show_colorspaces(axwidth=1.6, saturation=60)
+fig, axs = plot.show_colorspaces(axwidth=1.6, hue=0)
+fig, axs = plot.show_channels(
     'magma', 'rocket', 'fire', 'dusk',
     axwidth=1.4, minhue=-180, maxsat=300, rgb=False
 )
@@ -216,8 +216,8 @@
 axs[4].format(title='From list of colors')
 
 # Test the channels
-fig = plot.show_channels(cmap1, cmap2, axwidth=1.4, rgb=False)
-fig = plot.show_channels(
+fig, axs = plot.show_channels(cmap1, cmap2, axwidth=1.4, rgb=False)
+fig, axs = plot.show_channels(
     cmap3, cmap4, cmap5, minhue=-180,
     axwidth=1.4, rgb=False
 )
diff --git a/docs/colors.py b/docs/colors.py
@@ -30,15 +30,13 @@
 #
 # ProPlot adds new color names from the `XKCD color survey
 # <https://blog.xkcd.com/2010/05/03/color-survey-results/>`__  and
-# the `"Open color" <https://github.com/yeun/open-color>`__ Github project.
-# This was inspired by `seaborn
-# <https://seaborn.pydata.org/tutorial/color_palettes.html>`__. Use
-# `~proplot.show.show_colors` to generate tables of these colors. Note that
-# the matplotlib's native `X11 named colors
+# the `Open Color <https://github.com/yeun/open-color>`__ UI design color
+# palettes. You can use `~proplot.show.show_colors` to generate a table of these
+# colors. Note that the matplotlib's native `X11 named colors
 # <https://matplotlib.org/examples/color/named_colors.html>`__ are still
-# registered, but we encourage using colors from the tables instead, and
-# some of the X11 color names may be overwritten by the XKCD names. We prefer
-# the XKCD color names because the selection is larger and the names are
+# registered, but some of the X11 color names may be overwritten by the XKCD names,
+# and we encourage choosing colors from the below tables instead. ProPlot
+# registers XKCD colors because the selection is larger and the names are
 # more likely to match your intuition for what a color "should" look like.
 #
 # To reduce the number of registered color names to a more manageable size,
@@ -50,7 +48,7 @@
 
 # %%
 import proplot as plot
-figs = plot.show_colors()
+fig, axs = plot.show_colors()
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
diff --git a/docs/cycles.py b/docs/cycles.py
@@ -46,7 +46,7 @@
 
 # %%
 import proplot as plot
-fig = plot.show_cycles()
+fig, axs = plot.show_cycles()
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -19,8 +19,9 @@ dependencies:
   - pip:
     - ..
     - pyqt5
-    - jupytext
-    - nbsphinx
+    - sphinx>=3.0
     - sphinx-copybutton
     - sphinx_rtd_theme
+    - jupytext
+    - nbsphinx
     - git+https://github.com/lukelbd/sphinx-automodapi@v0.8.proplot-mods
diff --git a/docs/fonts.py b/docs/fonts.py
@@ -18,7 +18,7 @@
 # Font selection
 # ==============
 #
-# ProPlot registers several new font families and includes tools for adding
+# ProPlot registers several new fonts and includes tools for adding
 # your own fonts. These features are described below.
 #
 #
@@ -38,13 +38,12 @@
 # is `DejaVu Sans <https://dejavu-fonts.github.io>`__, which comes packaged with
 # matplotlib.
 #
-# Matplotlib uses DejaVu Sans in part because it includes glyphs
-# for a wider range of mathematical symbols. However in your opinion, DejaVu Sans
-# not very aesthetically pleasing or particularly readable, and it is
-# seldom used outside of the matplotlib ecosystem.
-# To improve the font selection and make things consistent across different
-# workspaces, ProPlot comes packaged with the open-source
-# `TeX Gyre <http://www.gust.org.pl/projects/e-foundry/tex-gyre>`__ font series
+# Matplotlib uses DejaVu Sans in part because it includes glyphs for a very wide
+# range of symbols, especially mathematical symbols. However DejaVu Sans is seldom
+# used outside of matplotlib and (in our opinion) is not very aesthetically pleasing.
+# To improve the font selection while keeping things consistent across different
+# workstations, ProPlot comes packaged with the open-source
+# `TeX Gyre font series <https://ctan.org/pkg/tex-gyre?lang=en>`__
 # and adds them as the default entries for all of matplotlib's font famlies:
 #
 # * The `Century <https://en.wikipedia.org/wiki/Century_type_family>`__ lookalike
@@ -58,27 +57,26 @@
 # * The `Avant Garde <https://en.wikipedia.org/wiki/ITC_Avant_Garde>`__ lookalike
 #   :rcraw:`font.fantasy` = ``'TeX Gyre Adventor'``.
 #
-# Thus after importing ProPlot, even on sparse Linux servers with limited font
-# selection, the default font will be a more conventional and aesthetically
-# pleasing Helvetica lookalike. The new font priority lists for each font family
-# are shown in the :ref:`default proplotrc file <ug_proplotrc>`.
+# Thus after importing ProPlot, the default font will be the more conventional
+# and aesthetically pleasing Helvetica lookalike
+# `TeX Gyre Heros <https://ctan.org/pkg/tex-gyre-heros>`__. The new font priority
+# lists for each font family are shown in the
+# :ref:`default proplotrc file <ug_proplotrc>`.
 #
 # To compare different fonts, use the `~proplot.show.show_fonts` command. By
-# default, this displays the *sans-serif* fonts available on your system and
-# included with ProPlot. The default table on a sparse Linux server is shown
+# default, this displays the *sans serif* fonts available on your system and
+# packaged with ProPlot. The default table on a sparse Linux server is shown
 # below. The "¤" symbol appears where characters for a particular font are
-# unavailable. When you are actually making plots, "¤" will be filled with
-# the character from a fallback font.
-#
-# It should be noted that most of the TeX Gyre fonts have limited character
-# availability. If your plots contain lots of mathematical symbols,
-# you may want to switch the default :rcraw:`font.family` to DejaVu Sans, which
-# is packaged with matplotlib, or `Fira Math <https://github.com/firamath/firamath>`__,
-# which is also packaged with ProPlot.
+# unavailable (when making plots, "¤" is replaced with the character from
+# a fallback font). Since most TeX Gyre fonts have limited
+# character sets, if your plots contain lots of mathematical symbols,
+# you may want to set :rcraw:`font.family` to DejaVu Sans or
+# `Fira Math <https://github.com/firamath/firamath>`__, which is packaged
+# with ProPlot.
 
 # %%
 import proplot as plot
-fig = plot.show_fonts()
+fig, axs = plot.show_fonts()
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -94,14 +92,13 @@
 # the :ref:`configuration section <ug_config>` for details.
 #
 # Sometimes the font you would like to use *is* installed, but the font file
-# is not stored under the matplotlib-compatible ``.ttf``, ``.otf``, or
-# ``.afm`` formats. For example, several macOS fonts are unavailable because
-# they are stored as ``.dfont`` collections. Also, while matplotlib nominally
-# supports ``.ttc`` collections, ProPlot manually removes them because
-# figures with ``.ttc`` fonts
+# is not stored under the matplotlib-compatible ``.ttf``, ``.otf``, or ``.afm``
+# formats. For example, several macOS fonts are unavailable because they are
+# stored as ``.dfont`` collections. Also, while matplotlib nominally supports
+# ``.ttc`` collections, ProPlot ignores them because figures with ``.ttc`` fonts
 # `cannot be saved as PDFs <https://github.com/matplotlib/matplotlib/issues/3135>`__.
-# You can get matplotlib to use these fonts by expanding the "collections"
-# into individual ``.ttf`` files with the
+# You can get matplotlib to use ``.dfont`` and ``.ttc`` collections by
+# expanding them into individual ``.ttf`` files with the
 # `DFontSplitter application <https://peter.upfold.org.uk/projects/dfontsplitter>`__,
 # then saving the files in-place or in the ``~/.proplot/fonts`` folder.
 #
diff --git a/docs/insets_panels.py b/docs/insets_panels.py
@@ -32,10 +32,9 @@
 # to the `~proplot.axes.Axes.panel` or `~proplot.axes.Axes.panel_axes` methods.
 # The resulting axes are instances of `~proplot.axes.CartesianAxes`.
 #
-# To generate "stacked" panels, simply call `~proplot.axes.Axes.panel` or
-# `~proplot.axes.Axes.panel_axes` more than once. To include panels when
-# centering spanning axis labels and super titles, pass
-# ``includepanels=True`` to `~proplot.figure.Figure`. Panels
+# To generate "stacked" panels, simply call `~proplot.axes.Axes.panel` more
+# than once. To include panels when centering spanning axis labels and super
+# titles, pass ``includepanels=True`` to `~proplot.figure.Figure`. Panels
 # :ref:`do not interfere with the tight layout algorithm <ug_tight>` and
 # :ref:`do not affect the subplot aspect ratios <ug_autosize>`.
 #
@@ -95,7 +94,7 @@
 
 # Panels do not interfere with subplot layout
 for ax, side in zip(axs, 'tlbr'):
-    ax.panel_axes(side, width='3em')
+    ax.panel(side, width='3em')
 axs.format(
     title='Title', suptitle='Complex arrangement of panels',
     collabels=['Column 1', 'Column 2'],
diff --git a/docs/subplots.py b/docs/subplots.py
@@ -53,9 +53,9 @@
 #
 # This algorithm also has the following notable properties:
 #
-# * For very simple subplot grids (e.g. ``plot.subplots(ncols=2, nrows=3)``),
-#   `aspect`, `axwidth`, and `axheight` apply to every subplot in the figure --
-#   not just the reference subplot.
+# * For very simple subplot grids (i.e. subplots created with the `ncols` and
+#   `nrows` arguments), the arguments `aspect`, `axwidth`, and `axheight` apply
+#   to every subplot in the figure -- not just the reference subplot.
 # * When the reference subplot `aspect ratio\
 #   <https://matplotlib.org/2.0.2/examples/pylab_examples/equal_aspect_ratio.html>`__
 #   has been manually overridden (e.g. with ``ax.set_aspect(1)``) or is set
@@ -144,27 +144,27 @@
 # Automatic subplot spacing
 # -------------------------
 #
-# By default, ProPlot applies a *tight layout* algorithm to every figure.
-# This algorithm automatically adjusts the space between subplot rows and
-# columns and the figure edge to accomadate labels. It can be disabled by
-# passing ``tight=False`` to `~proplot.ui.subplots`.
-#
+# In addition to automatic figure sizing, by default ProPlot applies a *tight layout*
+# algorithm to every figure. This algorithm automatically adjusts the space between
+# subplot rows and columns and the figure edge to accommodate labels.
+# It can be disabled by passing ``tight=False`` to `~proplot.ui.subplots`.
 # While matplotlib has `its own tight layout algorithm
 # <https://matplotlib.org/3.1.1/tutorials/intermediate/tight_layout_guide.html>`__,
-# ProPlot's algorithm permits variable spacing between subsequent subplot
-# rows and columns (see the new `~proplot.gridspec.GridSpec` class) and may
-# change the figure size (depending on the keyword arguments passed to
-# `~proplot.ui.subplots`).
+# ProPlot's algorithm may change the figure size to accommodate the correct spacing
+# and permits variable spacing between subsequent subplot rows and columns (see the
+# new `~proplot.gridspec.GridSpec` class for details).
 #
-# ProPlot's tight layout algorithm can also be easily overridden. When you
+# The tight layout algorithm can also be easily overridden. When you
 # pass a spacing argument like `left`, `right`, `top`, `bottom`, `wspace`, or
-# `hspace` to `~proplot.ui.subplots`, that value is always respected:
+# `hspace` to `~proplot.ui.subplots`, that value is always respected. For example:
 #
-# * With ``left='2em'``, the left margin is fixed but the right, bottom, and
-#   top margins are calculated automatically.
-# * With ``wspace=('3em', None)`` (and ``ncols=3``), the space between the
-#   first two columns is fixed, while the space between the second two columns
-#   is calculated automatically.
+# * ``left='2em'`` fixes the left margin, while the right, bottom, and
+#   top margins are determined automatically.
+# * ``wspace='1em'`` fixes the spaces between subplot columns, while the spaces
+#   between subplot rows are determined automatically.
+# * ``wspace=('3em', None)`` fixes the space between the first two columns of
+#   a three-column plot, while the space between the second two columns is
+#   determined automatically.
 #
 # The below examples demonstrate how the tight layout algorithm permits
 # variable spacing between subplot rows and columns.
@@ -201,7 +201,7 @@
 
 # Formatting that stress-tests the algorithm
 axs.format(
-    xlim=(-1.2, 1.2), ylim=(-1.2, 1.2), xlocator=1, ylocator=1,
+    xlim=(-1.5, 1.5), ylim=(-1.5, 1.5), xlocator=1, ylocator=1,
     suptitle='Tight layout with user overrides',
     rowlabels=['Row 1', 'Row 2', 'Row 3'],
     collabels=['Column 1', 'Column 2', 'Column 3', 'Column 4']
@@ -245,27 +245,29 @@
         wspace=('10pt', '20pt'), right='10mm'
     )
     panel = axs[2].panel_axes('r', width='2em')
+    panel.format(xlim=(0, 1))
 axs.format(
     suptitle='Arguments with arbitrary units',
-    xlabel='x axis', ylabel='y axis'
+    xlabel='x axis', ylabel='y axis',
+    xlim=(0, 1), ylim=(0, 1),
 )
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_abc:
 #
-# Subplot a-b-c labels
+# A-b-c subplot labels
 # --------------------
 #
 # ProPlot can be used to add "a-b-c" labels to subplots. This is possible
-# because `~proplot.ui.subplots` assigns unique
-# `~proplot.axes.Axes.number`\ s to each subplot. If you passed an `array` to
+# because `~proplot.ui.subplots` assigns unique `~proplot.axes.Axes.number`\ s
+# to each subplot. If you :ref:`passed an array <ug_intro>` to
 # `~proplot.ui.subplots`, the subplot numbers correspond to the numbers in
-# the array. Otherwise, if you used the `ncols` and `nrows` keyword
-# arguments, the number order is row-major by default but can be switched to
-# column-major by passing ``order='C'`` to `~proplot.ui.subplots`. The number
-# order also determines the subplot order in the
-# `~proplot.ui.SubplotsContainer` returned by `~proplot.ui.subplots`.
+# the array. If you used the `ncols` and `nrows` keyword arguments, the number
+# order is row-major by default but can be switched to column-major by passing
+# ``order='C'`` to `~proplot.ui.subplots`. The number order also determines the
+# subplot order in the `~proplot.ui.SubplotsContainer` returned by
+# `~proplot.ui.subplots`.
 #
 # To turn on "a-b-c" labels, set :rcraw:`abc` to ``True`` or pass
 # ``abc=True`` to `~proplot.axes.Axes.format` (see
@@ -287,29 +289,33 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_share:
 #
-# Shared and spanning labels
-# --------------------------
-#
-# Matplotlib has an "axis sharing" feature that holds axis limits the same
-# for axes within a grid of subplots. But this has no effect on the axis
-# labels and tick labels, which can lead to lots of redundancies.
+# Axis sharing
+# ------------
 #
-# To help you eliminate these redundancies, ProPlot introduces four
-# axis-sharing options and a new spanning label option, controlled by the
-# `share`, `sharex`, `sharey`, `span`, `spanx`, and `spany`
-# `~proplot.ui.subplots` keyword args.
+# 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. However there is no convenient way to enable
+# axis sharing between complex grids of subplots, nor is there a way to share axis
+# labels between subplots in the same row or column.
 #
-# #. Level ``1`` hides inner *x* and *y* axis labels.
-# #. Level ``2`` is the same as ``1``, but the *x* and *y* axis limits are locked.
-# #. Level ``3`` is the same as ``2``, but the *x* and *y* tick labels are hidden.
+# ProPlot expands upon this feature by introducing a new option for drawing
+# labels that "span" subplots in the same row or column, controlled by the
+# `spanx` and `spany` keywords, along with four axis-sharing "levels"
+# rather than just one, controlled with the `sharex` and `sharey` keywords:
 #
-# "Spanning labels" are centered *x* and *y* axis labels used for subplots
-# whose spines are on the same row or column. See the below example.
+# * Level ``0`` disables axis sharing.
+# * Level ``1`` shares duplicate *x* and *y* axis labels, but nothing else.
+# * Level ``2`` is the same as ``1``, but the *x* and *y* axis limits, ticks,
+#   and scales are also shared.
+# * Level ``3`` is the same as ``2``, but the *x* and *y* tick labels are
+#   also shared.
 #
-# Note that the the "shared" and "spanning" axes are determined automatically
-# based on the extent of each subplot in the `~proplot.gridspec.GridSpec`.
-# Since ProPlot uses just one `~proplot.gridspec.GridSpec` per figure, this
-# can be done with zero ambiguity.
+# These features are best illustrated by example (see below). Note that since
+# "shared" and "spanning" labels are determined automatically based on position of
+# each subplot in the `~proplot.gridspec.GridSpec`, these features work for
+# arbitrarily complex figures. Since ProPlot uses just one `~proplot.gridspec.GridSpec`
+# per figure, this can be done with zero ambiguity.
 
 # %%
 import proplot as plot
@@ -326,14 +332,14 @@
 # Same plot with different sharing and spanning settings
 for share in (0, 1, 2, 3):
     fig, axs = plot.subplots(
-        ncols=4, aspect=1, axwidth=1.2,
+        ncols=4, aspect=1, axwidth=1.06,
         sharey=share, spanx=share // 2
     )
     for ax, data in zip(axs, datas):
         on = ['off', 'on'][share // 2]
         ax.plot(data, cycle=colors)
         ax.format(
-            suptitle=f'Axis-sharing level: {share}, spanning labels {on}',
+            suptitle=f'Sharing level {share}, spanning labels {on}',
             grid=False, xlabel='spanning', ylabel='shared'
         )
 
diff --git a/docs/why.rst b/docs/why.rst
