Update demo text, add 'user' & 'fallback' keywords

Author: lukelbd

docs/1dplots.py

@@ -470,17 +470,21 @@
 # apply default *x* or *y* coordinates if you failed to provide them explicitly
 # and can *group* or *stack* successive columns of data if you pass 2D arrays instead
 # of 1D arrays -- just like `pandas`_. When bars are grouped, their widths and
-# positions are adjusted according to the number of bars in the group.
+# positions are adjusted according to the number of bars in the group. Grouping
+# is the default behavior and stacking can be enabled with ``stack=True``
+# or ``stacked=True``.
 #
 # The `~proplot.axes.PlotAxes.fill_between` and `~proplot.axes.PlotAxes.fill_betweenx`
 # commands have the new shorthands `~proplot.axes.PlotAxes.area`
 # and `~proplot.axes.PlotAxes.areax`. Similar to `~proplot.axes.PlotAxes.bar` and
 # `~proplot.axes.PlotAxes.barh`, they apply default *x* coordinates if you failed
 # to provide them explicitly, and can *overlay* or *stack* successive columns of
-# data if you pass 2D arrays instead of 1D arrays -- just like `pandas`_. Also, the
-# default *x* bounds for shading drawn with `~proplot.axes.PlotAxes.area` and *y*
-# bounds for shading drawn with `~proplot.axes.PlotAxes.areax` is now "sticky",
-# i.e. there is no padding between the shading and axes edges by default.
+# data if you pass 2D arrays instead of 1D arrays -- just like `pandas`_. Overlaying
+# is the default behavior but stacking can be enabled with ``stack=True`` or
+# ``stacked=True``. Also note the default *x* bounds for shading drawn with
+# `~proplot.axes.PlotAxes.area` and *y* bounds for shading drawn with
+# `~proplot.axes.PlotAxes.areax` is now "sticky", i.e. there is no padding
+# between the shading and axes edges by default.
 
 # .. important::
 #

docs/fonts.py

@@ -80,29 +80,29 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_fonts_math:
 #
-# Math fonts
-# ----------
-#
-# Proplot changes the default :rcraw:`mathtext.fontset` to ``'custom'``.
-# This means that LaTeX-generated math text in a given string (i.e.,
-# text surrounded by ``'$dollar signs$'``) uses the same font
-# family as non-math text (see the matplotlib `math text guide
-# <https://matplotlib.org/stable/tutorials/text/mathtext.html#custom-fonts>`__
-# for details). This improves the consistency of figure text when switching
-# between different fonts. However, if you are need unusual math symbols
-# or complex math operators, you may want to change :rcraw:`font.name` to
-# something more suitable for math (e.g., the proplot-packaged font
-# ``'Fira Math'`` or the matplotlib-packaged font ``'DejaVu Sans'``; see
-# `this page <https://github.com/firamath/firamath>`__ for more on Fira Math).
-# Alternatively, you can change the math text without affecting non-math text
-# by setting :rcraw:`mathtext.fontset` back to one of matplotlib's
-# math-specialized font sets (e.g., ``'stixsans'`` or ``'dejavusans'``).
+# Math text fonts
+# ---------------
+#
+# In matplotlib, math text rendered by TeX can be produced by surrounding
+# an expression with ``$dollar signs$``. To help math text jive better with
+# the new default :ref:`non-math text font <ug_fonts_included>`, proplot changes
+# :rcraw:`mathtext.fontset` to ``'custom'``. This means that math is drawn with
+# the italicized version of the non-math font (see the matplotlib `math text
+# guide <https://matplotlib.org/stable/tutorials/text/mathtext.html#custom-fonts>`__
+# for details). This generally improves the appearance of figures with simple
+# math expressions. However, if you need unusual math symbols or complex math
+# operators, you may want to change :rcraw:`font.name` to something more suitable
+# for math (e.g., the proplot-packaged font ``'Fira Math'`` or the matplotlib-packaged
+# font ``'DejaVu Sans'``; see `this page <https://github.com/firamath/firamath>`__ for
+# more on Fira Math). Alternatively, you can change the math text font alone by setting
+# :rcraw:`mathtext.fontset` back to one of matplotlib's math-specialized font sets
+# (e.g., ``'stixsans'`` or ``'dejavusans'``).
 #
 # A table of math text containing the sans-serif fonts packaged with proplot is shown
-# below. The dummy character "¤" is shown where a given math character is unavailable
+# below. The dummy glyph "¤" is shown where a given math character is unavailable
 # for a particular font (in practice, the fallback font :rc:`mathtext.fallback` is used
-# whenever a math character is unavailable, but the demo function disables this fallback
-# font in order to highlight the missing characters).
+# whenever a math character is unavailable, but `~proplot.demos.show_fonts` disables
+# this fallback font in order to highlight the missing characters).
 #
 # .. note::
 #

docs/subplots.py

@@ -406,18 +406,23 @@
 # various `~proplot.axes.Axes.legend` spacing and padding arguments; various
 # `~proplot.axes.Axes.format` font size and padding arguments; the line width and
 # marker size arguments passed to `~proplot.axes.PlotAxes` commands; and all
-# applicable `~proplot.config.rc` settings. This feature is powered by the
-# `~proplot.utils.units` function.
+# applicable `~proplot.config.rc` settings, e.g. :rcraw:`subplots.refwidth`,
+# :rcraw:`legend.columnspacing`, and :rcraw:`axes.labelpad`. This feature is
+# powered by the physical units engine `~proplot.utils.units`.
 #
-# A table of acceptable physical units is found :ref:`here <units_table>`.
-# They include centimeters, millimeters, pixels,
-# `em-heights <https://en.wikipedia.org/wiki/Em_(typography)>`__,
+# When one of these keyword arguments is numeric, a default physical unit is
+# used. For subplot and figure sizes, the defult unit is inches. For gridspec and
+# legend spaces, the default unit is `em-widths
+# <https://en.wikipedia.org/wiki/Em_(typography)>`__.
+# For font sizes, text padding, and
+# line widths, the default unit is
+# `points <https://en.wikipedia.org/wiki/Point_(typography)>`__.
+# See the relevant documentation in the :ref:`API reference <api>` for details.
+# A table of acceptable physical units is found :ref:`here <units_table>`
+# -- they include centimeters, millimeters, pixels,
+# `em-widths <https://en.wikipedia.org/wiki/Em_(typography)>`__,
 # `en-heights <https://en.wikipedia.org/wiki/En_(typography)>`__,
 # and `points <https://en.wikipedia.org/wiki/Point_(typography)>`__.
-# The default physical unit (assumed when an argument is numeric) depends on the
-# context. For subplot and figure sizes, it is inches. For gridspec and legend spaces,
-# it is em-widths. For font sizes, text padding, and line widths, it is points.
-# See the relevant documentation in the :ref:`API reference <api>` for details.
 
 # %%
 import proplot as pplt

proplot/demos.py

@@ -803,7 +803,9 @@ def show_colors(*, nhues=17, minsat=10, unknown='User', include=None, ignore=Non
     return fig, axs
 
 
-def show_fonts(*args, family=None, text=None, math=False, **kwargs):
+def show_fonts(
+    *args, family=None, user=None, text=None, math=False, fallback=False, **kwargs
+):
     """
     Generate a table of fonts. If a glyph for a particular font is unavailable,
     it is replaced with the "¤" dummy character.
@@ -818,17 +820,25 @@ def show_fonts(*args, family=None, text=None, math=False, **kwargs):
         :rcraw:`font.sans-serif` fonts are shown.
     family \
 : {'tex-gyre', 'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy'}, optional
-        If provided, the *available* fonts in the corresponding families are shown.
-        The fonts belonging to these families are listed under the :rcraw:`font.serif`,
+        The family from which *available* fonts are shown. Default is ``'sans-serif'``
+        if no arguments were provided. Otherwise the default is to not show family
+        fonts. The fonts belonging to each family are listed under :rcraw:`font.serif`,
         :rcraw:`font.sans-serif`, :rcraw:`font.monospace`, :rcraw:`font.cursive`, and
-        :rcraw:`font.fantasy` settings. The special family ``'tex-gyre'`` includes
-        the `TeX Gyre <http://www.gust.org.pl/projects/e-foundry/tex-gyre>`__ fonts.
+        :rcraw:`font.fantasy`. The special family ``'tex-gyre'`` includes the
+        `TeX Gyre <http://www.gust.org.pl/projects/e-foundry/tex-gyre>`__ fonts.
+    user : bool, optional
+        Whether to include fonts in `~proplot.config.Configurator.user_folder` and
+        `~proplot.config.Configurator.local_folders` at the top of the table. Default
+        is ``True`` if called without any arguments and ``False`` otherwise.
     text : str, optional
         The sample text shown for each font. If not passed then default math or
         non-math sample text is used.
     math : bool, default: False
         Whether the default sample text should show non-math Latin characters or
         or math equations and Greek letters.
+    fallback : bool, default: False
+        Whether to use the fallback font :rcraw:`mathtext.fallback` for unavailable
+        characters. If ``False`` the dummy glyph "¤" is shown for missing characters.
     **kwargs
         Additional font properties passed to `~matplotlib.font_manager.FontProperties`.
         Default size is ``12`` and default weight, style, and strength are ``'normal'``.
@@ -875,8 +885,9 @@ def show_fonts(*args, family=None, text=None, math=False, **kwargs):
             warnings._warn_proplot(f'Input font name {opts[:1]!r} not found. Skipping.')
 
     # Add user and family FontProperties.
-    if not args and family is None:
-        family = 'sans-serif'
+    user = _not_none(user, not args and family is None)
+    family = _not_none(family, None if args else 'sans-serif')
+    if user:
         paths = _get_data_folders('fonts', default=False)
         for font in all_fonts:  # fonts sorted by unique name
             if os.path.dirname(font.fname) in paths:
@@ -894,33 +905,36 @@ def show_fonts(*args, family=None, text=None, math=False, **kwargs):
                 props.append(mfonts.FontProperties(name, **kwargs))
 
     # The default sample text
+    linespacing = 0.8 if text is None and math else 1.2
     if text is None:
         if not math:
             text = (
-                'the quick brown fox jumps over a lazy dog . , + -'
+                'the quick brown fox jumps over a lazy dog 01234 ; . , + - * ^ () ||'
                 '\n'
-                'THE QUICK BROWN FOX JUMPS OVER A LAZY DOG ! ? & # %'
+                'THE QUICK BROWN FOX JUMPS OVER A LAZY DOG 56789 : ! ? & # % $ [] {}'
             )
         else:
             text = (
+                '\n'
                 r'$\alpha\beta$ $\Gamma\gamma$ $\Delta\delta$ '
                 r'$\epsilon\zeta\eta$ $\Theta\theta$ $\kappa\mu\nu$ '
                 r'$\Lambda\lambda$ $\Pi\pi$ $\xi\rho\tau\chi$ $\Sigma\sigma$ '
                 r'$\Phi\phi$ $\Psi\psi$ $\Omega\omega$ '
-                r'$\ll { }^k \gg [ ]_l \propto ( )^m \cdot \left<\right>_n$'
+                r'$\{ \; \}^i$ $[ \; ]_j$ $( \; )^k$ $\left<  \right>_n$'
                 '\n'
                 r'$0^a + 1_b - 2^c \times 3_d = '
                 r'4.0^e \equiv 5.0_f \approx 6.0^g \sim 7_h \leq 8^i \geq 9_j'
-                r'\sum X \ll \int Y \gg \oint Z \propto \prod Q$'
-                '\n'
+                r'\ll \prod \, P \gg \sum \, Q \, '
+                r'\int \, Y \mathrm{d}y \propto \oint \;\, Z \mathrm{d}z$'
             )
 
     # Settings for rendering math text
     ctx = {'mathtext.fontset': 'custom'}
-    if _version_mpl < '3.4':
-        ctx['mathtext.fallback_to_cm'] = False
-    else:
-        ctx['mathtext.fallback'] = None
+    if not fallback:
+        if _version_mpl < '3.4':
+            ctx['mathtext.fallback_to_cm'] = False
+        else:
+            ctx['mathtext.fallback'] = None
     if 'size' not in kwargs:
         for prop in props:
             if prop.get_size() == rc['font.size']:
@@ -939,6 +953,7 @@ def show_fonts(*args, family=None, text=None, math=False, **kwargs):
     for ax, prop in zip(axs, props):
         name = prop.get_family()[0]
         ax.text(
-            0, 0.5, f'{name}:\n{text}', ha='left', va='center', fontproperties=prop
+            0, 0.5, f'{name}:\n{text} ', ha='left', va='center',
+            linespacing=linespacing, fontproperties=prop
         )
     return fig, axs