Merge pull request matplotlib#15696 from anntzer/mathmpl-fontset

Improve mathtext.fontset docs and fix :mathmpl: cache bug.

Author: QuLogic

doc/_static/cm_fontset.png

@@ -3320,27 +3320,31 @@ def __init__(self, output):
         """
         self._output = output.lower()
 
-    @functools.lru_cache(50)
-    def parse(self, s, dpi = 72, prop = None):
+    def parse(self, s, dpi=72, prop=None):
         """
-        Parse the given math expression *s* at the given *dpi*.  If
-        *prop* is provided, it is a
-        :class:`~matplotlib.font_manager.FontProperties` object
-        specifying the "default" font to use in the math expression,
-        used for all non-math text.
+        Parse the given math expression *s* at the given *dpi*.  If *prop* is
+        provided, it is a `.FontProperties` object specifying the "default"
+        font to use in the math expression, used for all non-math text.
 
         The results are cached, so multiple calls to :meth:`parse`
         with the same expression should be fast.
         """
+        # lru_cache can't decorate parse() directly because the ps.useafm and
+        # mathtext.fontset rcParams also affect the parse (e.g. by affecting
+        # the glyph metrics).
+        return self._parse_cached(
+            s, dpi, prop, rcParams['ps.useafm'], rcParams['mathtext.fontset'])
+
+    @functools.lru_cache(50)
+    def _parse_cached(self, s, dpi, prop, ps_useafm, fontset):
 
         if prop is None:
             prop = FontProperties()
 
-        if self._output == 'ps' and rcParams['ps.useafm']:
+        if self._output == 'ps' and ps_useafm:
             font_output = StandardPsFonts(prop)
         else:
             backend = self._backend_mapping[self._output]()
-            fontset = rcParams['mathtext.fontset'].lower()
             fontset_class = cbook._check_getitem(
                 self._font_type_mapping, fontset=fontset)
             font_output = fontset_class(prop, backend)

doc/_static/stix_fontset.png

@@ -1,15 +1,13 @@
 import hashlib
 import os
-import sys
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
 import sphinx
 
-from matplotlib import rcParams
+import matplotlib as mpl
 from matplotlib import cbook
 from matplotlib.mathtext import MathTextParser
-rcParams['mathtext.fontset'] = 'cm'
 mathtext_parser = MathTextParser("Bitmap")
 
 
@@ -19,7 +17,7 @@ class latex_math(nodes.General, nodes.Element):
 
 
 def fontset_choice(arg):
-    return directives.choice(arg, ['cm', 'stix', 'stixsans'])
+    return directives.choice(arg, MathTextParser._font_type_mapping)
 
 
 def math_role(role, rawtext, text, lineno, inliner,
@@ -61,36 +59,34 @@ def run(self):
 # This uses mathtext to render the expression
 def latex2png(latex, filename, fontset='cm'):
     latex = "$%s$" % latex
-    orig_fontset = rcParams['mathtext.fontset']
-    rcParams['mathtext.fontset'] = fontset
-    if os.path.exists(filename):
-        depth = mathtext_parser.get_depth(latex, dpi=100)
-    else:
-        try:
-            depth = mathtext_parser.to_png(filename, latex, dpi=100)
-        except Exception:
-            cbook._warn_external("Could not render math expression %s" % latex,
-                                 Warning)
-            depth = 0
-    rcParams['mathtext.fontset'] = orig_fontset
-    sys.stdout.write("#")
-    sys.stdout.flush()
+    with mpl.rc_context({'mathtext.fontset': fontset}):
+        if os.path.exists(filename):
+            depth = mathtext_parser.get_depth(latex, dpi=100)
+        else:
+            try:
+                depth = mathtext_parser.to_png(filename, latex, dpi=100)
+            except Exception:
+                cbook._warn_external(
+                    f"Could not render math expression {latex}")
+                depth = 0
     return depth
 
 
 # LaTeX to HTML translation stuff:
 def latex2html(node, source):
     inline = isinstance(node.parent, nodes.TextElement)
     latex = node['latex']
-    name = 'math-%s' % hashlib.md5(latex.encode()).hexdigest()[-10:]
+    fontset = node['fontset']
+    name = 'math-{}'.format(
+        hashlib.md5((latex + fontset).encode()).hexdigest()[-10:])
 
     destdir = os.path.join(setup.app.builder.outdir, '_images', 'mathmpl')
     if not os.path.exists(destdir):
         os.makedirs(destdir)
     dest = os.path.join(destdir, '%s.png' % name)
     path = '/'.join((setup.app.builder.imgpath, 'mathmpl'))
 
-    depth = latex2png(latex, dest, node['fontset'])
+    depth = latex2png(latex, dest, fontset)
 
     if inline:
         cls = ''

doc/_static/stixsans_fontset.png

@@ -224,21 +224,44 @@
     ``\mathrm{\mathsf{sansserif}}``  :math-stix:`\mathrm{\mathsf{sansserif}}`
     ================================ =========================================
 
-There are also three global "font sets" to choose from, which are
+There are also five global "font sets" to choose from, which are
 selected using the ``mathtext.fontset`` parameter in :ref:`matplotlibrc
 <matplotlibrc-sample>`.
 
-``cm``: **Computer Modern (TeX)**
+``dejavusans``: DejaVu Sans
 
-.. image:: ../../_static/cm_fontset.png
+    .. mathmpl::
+       :fontset: dejavusans
 
-``stix``: **STIX** (designed to blend well with Times)
+       \mathcal{R} \prod_{i=\alpha}^{\infty} a_i \sin\left(2\pi fx_i\right)
 
-.. image:: ../../_static/stix_fontset.png
+``dejavuserif``: DejaVu Serif
 
-``stixsans``: **STIX sans-serif**
+    .. mathmpl::
+       :fontset: dejavuserif
 
-.. image:: ../../_static/stixsans_fontset.png
+       \mathcal{R} \prod_{i=\alpha}^{\infty} a_i \sin\left(2\pi fx_i\right)
+
+``cm``: Computer Modern (TeX)
+
+    .. mathmpl::
+       :fontset: cm
+
+       \mathcal{R} \prod_{i=\alpha}^{\infty} a_i \sin\left(2\pi fx_i\right)
+
+``stix``: STIX (designed to blend well with Times)
+
+    .. mathmpl::
+       :fontset: stix
+
+       \mathcal{R} \prod_{i=\alpha}^{\infty} a_i \sin\left(2\pi fx_i\right)
+
+``stixsans``: STIX sans-serif
+
+    .. mathmpl::
+       :fontset: stixsans
+
+       \mathcal{R} \prod_{i=\alpha}^{\infty} a_i \sin\left(2\pi fx_i\right)
 
 Additionally, you can use ``\mathdefault{...}`` or its alias
 ``\mathregular{...}`` to use the font used for regular text outside of