From 9902c38db9a257c64b42172a6d0a8cf4173f5b58 Mon Sep 17 00:00:00 2001
From: Nelle Varoquaux <nelle.varoquaux@gmail.com>
Date: Fri, 7 Sep 2018 14:27:24 -0700
Subject: [PATCH 1/5] Merge pull request #11928 from anntzer/sphinx18

Update doc/conf.py to avoid warnings with (future) sphinx 1.8.
---
 doc/conf.py             | 8 ++++++--
 doc/sphinxext/github.py | 4 ----
 2 files changed, 6 insertions(+), 6 deletions(-)

--- a/doc/conf.py
+++ b/doc/conf.py
@@ -22,6 +22,7 @@ from glob import glob
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 sys.path.append(os.path.abspath('.'))
+sys.path.append('.')
 
 # General configuration
 # ---------------------
@@ -39,9 +40,9 @@ extensions = [
     'IPython.sphinxext.ipython_directive',
     'numpydoc',  # Needs to be loaded *after* autodoc.
     'sphinx_gallery.gen_gallery',
-    'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.only_directives',
     'matplotlib.sphinxext.plot_directive',
+    'matplotlib.sphinxext.mathmpl',
     'sphinxext.custom_roles',
     'sphinxext.github',
     'sphinxext.math_symbol_table',
@@ -93,7 +94,10 @@ if not has_dot:
 autosummary_generate = True
 
 autodoc_docstring_signature = True
-autodoc_default_flags = ['members', 'undoc-members']
+if sphinx.version_info < (1, 8):
+    autodoc_default_flags = ['members', 'undoc-members']
+else:
+    autodoc_default_options = {'members': None, 'undoc-members': None}
 
 intersphinx_mapping = {
 }
--- a/doc/sphinxext/github.py
+++ b/doc/sphinxext/github.py
@@ -75,7 +75,6 @@ def ghissue_role(name, rawtext, text, li
         prb = inliner.problematic(rawtext, rawtext, msg)
         return [prb], [msg]
     app = inliner.document.settings.env.app
-    #app.info('issue %r' % text)
     if 'pull' in name.lower():
         category = 'pull'
     elif 'issue' in name.lower():
@@ -105,7 +104,6 @@ def ghuser_role(name, rawtext, text, lin
     :param content: The directive content for customization.
     """
     app = inliner.document.settings.env.app
-    #app.info('user link %r' % text)
     ref = 'https://www.github.com/' + text
     node = nodes.reference(rawtext, text, refuri=ref, **options)
     return [node], []
@@ -126,7 +124,6 @@ def ghcommit_role(name, rawtext, text, l
     :param content: The directive content for customization.
     """
     app = inliner.document.settings.env.app
-    #app.info('user link %r' % text)
     try:
         base = app.config.github_project_url
         if not base:
@@ -146,7 +143,6 @@ def setup(app):
 
     :param app: Sphinx application context.
     """
-    app.info('Initializing GitHub plugin')
     app.add_role('ghissue', ghissue_role)
     app.add_role('ghpull', ghissue_role)
     app.add_role('ghuser', ghuser_role)
--- /dev/null
+++ b/doc/users/next_whats_new/2018-09-15-AL.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+``:math:`` directive renamed to ``:mathmpl:``
+`````````````````````````````````````````````
+
+The ``:math:`` rst role provided by `matplotlib.sphinxext.mathmpl` has been
+renamed to ``:mathmpl:`` to avoid conflicting with the ``:math:`` role that
+Sphinx 1.8 provides by default.  (``:mathmpl:`` uses Matplotlib to render math
+expressions to images embedded in html, whereas Sphinx uses MathJax.)
+
+When using Sphinx<1.8, both names (``:math:`` and ``:mathmpl:``) remain
+available for backcompatibility.
--- a/lib/matplotlib/sphinxext/mathmpl.py
+++ b/lib/matplotlib/sphinxext/mathmpl.py
@@ -1,15 +1,14 @@
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
-
 import six
-
+import hashlib
 import os
 import sys
-from hashlib import md5
+import warnings
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-import warnings
+import sphinx
 
 from matplotlib import rcParams
 from matplotlib.mathtext import MathTextParser
@@ -66,7 +65,7 @@ def latex2png(latex, filename, fontset='
 def latex2html(node, source):
     inline = isinstance(node.parent, nodes.TextElement)
     latex = node['latex']
-    name = 'math-%s' % md5(latex.encode()).hexdigest()[-10:]
+    name = 'math-%s' % hashlib.md5(latex.encode()).hexdigest()[-10:]
 
     destdir = os.path.join(setup.app.builder.outdir, '_images', 'mathmpl')
     if not os.path.exists(destdir):
@@ -115,9 +114,13 @@ def setup(app):
     app.add_node(latex_math,
                  html=(visit_latex_math_html, depart_latex_math_html),
                  latex=(visit_latex_math_latex, depart_latex_math_latex))
-    app.add_role('math', math_role)
-    app.add_directive('math', math_directive,
+    app.add_role('mathmpl', math_role)
+    app.add_directive('mathmpl', math_directive,
                       True, (0, 0, 0), **options_spec)
+    if sphinx.version_info < (1, 8):
+        app.add_role('math', math_role)
+        app.add_directive('math', math_directive,
+                          True, (0, 0, 0), **options_spec)
 
     metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
     return metadata
--- a/tutorials/text/mathtext.py
+++ b/tutorials/text/mathtext.py
@@ -1,353 +1,340 @@
-"""
+r"""
 Writing mathematical expressions
 ================================
 
 An introduction to writing mathematical expressions in Matplotlib.
 
-You can use a subset TeX markup in any matplotlib text string by
-placing it inside a pair of dollar signs ($).
+You can use a subset TeX markup in any matplotlib text string by placing it
+inside a pair of dollar signs ($).
 
-Note that you do not need to have TeX installed, since matplotlib
-ships its own TeX expression parser, layout engine and fonts.  The
-layout engine is a fairly direct adaptation of the layout algorithms
-in Donald Knuth's TeX, so the quality is quite good (matplotlib also
-provides a ``usetex`` option for those who do want to call out to TeX
-to generate their text (see :doc:`/tutorials/text/usetex`).
-"""
+Note that you do not need to have TeX installed, since Matplotlib ships
+its own TeX expression parser, layout engine, and fonts.  The layout engine
+is a fairly direct adaptation of the layout algorithms in Donald Knuth's
+TeX, so the quality is quite good (matplotlib also provides a ``usetex``
+option for those who do want to call out to TeX to generate their text (see
+:doc:`/tutorials/text/usetex`).
+
+Any text element can use math text.  You should use raw strings (precede the
+quotes with an ``'r'``), and surround the math text with dollar signs ($), as
+in TeX. Regular text and mathtext can be interleaved within the same string.
+Mathtext can use DejaVu Sans (default), DejaVu Serif, the Computer Modern fonts
+(from (La)TeX), `STIX <http://www.stixfonts.org/>`_ fonts (with are designed
+to blend well with Times), or a Unicode font that you provide.  The mathtext
+font can be selected with the customization variable ``mathtext.fontset`` (see
+:doc:`/tutorials/introductory/customizing`)
+
+Here is a simple example::
+
+    # plain text
+    plt.title('alpha > beta')
+
+produces "alpha > beta".
+
+Whereas this::
+
+    # math text
+    plt.title(r'$\alpha > \beta$')
+
+produces ":mathmpl:`\alpha > \beta`".
+
+.. note::
+   Mathtext should be placed between a pair of dollar signs ($). To make it
+   easy to display monetary values, e.g., "$100.00", if a single dollar sign
+   is present in the entire string, it will be displayed verbatim as a dollar
+   sign.  This is a small change from regular TeX, where the dollar sign in
+   non-math text would have to be escaped ('\\\$').
+
+.. note::
+   While the syntax inside the pair of dollar signs ($) aims to be TeX-like,
+   the text outside does not.  In particular, characters such as::
+
+     # $ % & ~ _ ^ \ { } \( \) \[ \]
+
+   have special meaning outside of math mode in TeX.  Therefore, these
+   characters will behave differently depending on the rcParam ``text.usetex``
+   flag.  See the :doc:`usetex tutorial </tutorials/text/usetex>` for more
+   information.
+
+Subscripts and superscripts
+---------------------------
+
+To make subscripts and superscripts, use the ``'_'`` and ``'^'`` symbols::
+
+    r'$\alpha_i > \beta_i$'
+
+.. math::
+
+    \alpha_i > \beta_i
+
+Some symbols automatically put their sub/superscripts under and over the
+operator.  For example, to write the sum of :mathmpl:`x_i` from :mathmpl:`0` to
+:mathmpl:`\infty`, you could do::
+
+    r'$\sum_{i=0}^\infty x_i$'
+
+.. math::
+
+    \sum_{i=0}^\infty x_i
+
+Fractions, binomials, and stacked numbers
+-----------------------------------------
+
+Fractions, binomials, and stacked numbers can be created with the
+``\frac{}{}``, ``\binom{}{}`` and ``\stackrel{}{}`` commands, respectively::
+
+    r'$\frac{3}{4} \binom{3}{4} \stackrel{3}{4}$'
+
+produces
+
+.. math::
+
+    \frac{3}{4} \binom{3}{4} \stackrel{3}{4}
+
+Fractions can be arbitrarily nested::
+
+    r'$\frac{5 - \frac{1}{x}}{4}$'
+
+produces
+
+.. math::
+
+    \frac{5 - \frac{1}{x}}{4}
+
+Note that special care needs to be taken to place parentheses and brackets
+around fractions.  Doing things the obvious way produces brackets that are too
+small::
+
+    r'$(\frac{5 - \frac{1}{x}}{4})$'
+
+.. math ::
+
+    (\frac{5 - \frac{1}{x}}{4})
+
+The solution is to precede the bracket with ``\left`` and ``\right`` to inform
+the parser that those brackets encompass the entire object.::
+
+    r'$\left(\frac{5 - \frac{1}{x}}{4}\right)$'
+
+.. math ::
+
+    \left(\frac{5 - \frac{1}{x}}{4}\right)
+
+Radicals
+--------
+
+Radicals can be produced with the ``\sqrt[]{}`` command.  For example::
+
+    r'$\sqrt{2}$'
+
+.. math ::
+
+    \sqrt{2}
+
+Any base can (optionally) be provided inside square brackets.  Note that the
+base must be a simple expression, and can not contain layout commands such as
+fractions or sub/superscripts::
+
+    r'$\sqrt[3]{x}$'
+
+.. math ::
+
+    \sqrt[3]{x}
+
+.. _mathtext-fonts:
+
+Fonts
+-----
+
+The default font is *italics* for mathematical symbols.
+
+.. note::
 
-###############################################################################
-# Any text element can use math text.  You should use raw strings (precede the
-# quotes with an ``'r'``), and surround the math text with dollar signs ($), as in
-# TeX. Regular text and mathtext can be interleaved within the same string.
-# Mathtext can use DejaVu Sans (default), DejaVu Serif, the Computer Modern fonts
-# (from (La)TeX), `STIX <http://www.stixfonts.org/>`_ fonts (with are designed
-# to blend well with Times), or a Unicode font that you provide.  The mathtext
-# font can be selected with the customization variable ``mathtext.fontset`` (see
-# :doc:`/tutorials/introductory/customizing`)
-#
-# .. note::
-#    On `"narrow" <http://wordaligned.org/articles/narrow-python>`_ builds
-#    of Python, if you use the STIX fonts you should also set
-#    ``ps.fonttype`` and ``pdf.fonttype`` to 3 (the default), not 42.
-#    Otherwise `some characters will not be visible
-#    <http://thread.gmane.org/gmane.comp.python.matplotlib.general/19963/focus=19978>`_.
-#
-# Here is a simple example::
-#
-#     # plain text
-#     plt.title('alpha > beta')
-#
-# produces "alpha > beta".
-#
-# Whereas this::
-#
-#     # math text
-#     plt.title(r'$\alpha > \beta$')
-#
-# produces ":math:`\alpha > \beta`".
-#
-# .. note::
-#    Mathtext should be placed between a pair of dollar signs ($).  To
-#    make it easy to display monetary values, e.g., "$100.00", if a
-#    single dollar sign is present in the entire string, it will be
-#    displayed verbatim as a dollar sign.  This is a small change from
-#    regular TeX, where the dollar sign in non-math text would have to
-#    be escaped ('\\\$').
-#
-# .. note::
-#    While the syntax inside the pair of dollar signs ($) aims to be
-#    TeX-like, the text outside does not.  In particular, characters
-#    such as::
-#
-#      # $ % & ~ _ ^ \ { } \( \) \[ \]
-#
-#    have special meaning outside of math mode in TeX.  Therefore, these
-#    characters will behave differently depending on the rcParam
-#    ``text.usetex`` flag.  See the :doc:`usetex tutorial
-#    </tutorials/text/usetex>` for more information.
-#
-# Subscripts and superscripts
-# ---------------------------
-#
-# To make subscripts and superscripts, use the ``'_'`` and ``'^'`` symbols::
-#
-#     r'$\alpha_i > \beta_i$'
-#
-# .. math::
-#
-#     \alpha_i > \beta_i
-#
-# Some symbols automatically put their sub/superscripts under and over
-# the operator.  For example, to write the sum of :math:`x_i` from :math:`0` to
-# :math:`\infty`, you could do::
-#
-#     r'$\sum_{i=0}^\infty x_i$'
-#
-# .. math::
-#
-#     \sum_{i=0}^\infty x_i
-#
-# Fractions, binomials and stacked numbers
-# ----------------------------------------
-#
-# Fractions, binomials and stacked numbers can be created with the
-# ``\frac{}{}``, ``\binom{}{}`` and ``\stackrel{}{}`` commands,
-# respectively::
-#
-#     r'$\frac{3}{4} \binom{3}{4} \stackrel{3}{4}$'
-#
-# produces
-#
-# .. math::
-#
-#     \frac{3}{4} \binom{3}{4} \stackrel{3}{4}
-#
-# Fractions can be arbitrarily nested::
-#
-#     r'$\frac{5 - \frac{1}{x}}{4}$'
-#
-# produces
-#
-# .. math::
-#
-#     \frac{5 - \frac{1}{x}}{4}
-#
-# Note that special care needs to be taken to place parentheses and brackets around
-# fractions.  Doing things the obvious way produces brackets that are
-# too small::
-#
-#     r'$(\frac{5 - \frac{1}{x}}{4})$'
-#
-# .. math ::
-#
-#     (\frac{5 - \frac{1}{x}}{4})
-#
-# The solution is to precede the bracket with ``\left`` and ``\right``
-# to inform the parser that those brackets encompass the entire object.::
-#
-#     r'$\left(\frac{5 - \frac{1}{x}}{4}\right)$'
-#
-# .. math ::
-#
-#     \left(\frac{5 - \frac{1}{x}}{4}\right)
-#
-# Radicals
-# --------
-#
-# Radicals can be produced with the ``\sqrt[]{}`` command.  For example::
-#
-#     r'$\sqrt{2}$'
-#
-# .. math ::
-#
-#     \sqrt{2}
-#
-# Any base can (optionally) be provided inside square brackets.  Note
-# that the base must be a simple expression, and can not contain layout
-# commands such as fractions or sub/superscripts::
-#
-#     r'$\sqrt[3]{x}$'
-#
-# .. math ::
-#
-#     \sqrt[3]{x}
-#
-# .. _mathtext-fonts:
-#
-# Fonts
-# -----
-#
-# The default font is *italics* for mathematical symbols.
-#
-# .. note::
-#
-#    This default can be changed using the ``mathtext.default`` rcParam.
-#    This is useful, for example, to use the same font as regular
-#    non-math text for math text, by setting it to ``regular``.
-#
-# To change fonts, e.g., to write "sin" in a Roman font, enclose the text
-# in a font command::
-#
-#     r'$s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)$'
-#
-# .. math::
-#
-#     s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)
-#
-# More conveniently, many commonly used function names that are typeset in a
-# Roman font have shortcuts.  So the expression above could be written
-# as follows::
-#
-#     r'$s(t) = \mathcal{A}\sin(2 \omega t)$'
-#
-# .. math::
-#
-#     s(t) = \mathcal{A}\sin(2 \omega t)
-#
-# Here "s" and "t" are variable in italics font (default), "sin" is in
-# Roman font, and the amplitude "A" is in calligraphy font.  Note in the
-# example above the calligraphy ``A`` is squished into the ``sin``.  You
-# can use a spacing command to add a little whitespace between them::
-#
-#     s(t) = \mathcal{A}\/\sin(2 \omega t)
-#
-# .. math::
-#
-#     s(t) = \mathcal{A}\/\sin(2 \omega t)
-#
-# The choices available with all fonts are:
-#
-#     ============================ ==================================
-#     Command                      Result
-#     ============================ ==================================
-#     ``\mathrm{Roman}``           :math:`\mathrm{Roman}`
-#     ``\mathit{Italic}``          :math:`\mathit{Italic}`
-#     ``\mathtt{Typewriter}``      :math:`\mathtt{Typewriter}`
-#     ``\mathcal{CALLIGRAPHY}``    :math:`\mathcal{CALLIGRAPHY}`
-#     ============================ ==================================
-#
-# .. role:: math-stix(math)
-#    :fontset: stix
-#
-# When using the `STIX <http://www.stixfonts.org/>`_ fonts, you also have the choice of:
-#
-#     ====================================== =========================================
-#     Command                                Result
-#     ====================================== =========================================
-#     ``\mathbb{blackboard}``                :math-stix:`\mathbb{blackboard}`
-#     ``\mathrm{\mathbb{blackboard}}``       :math-stix:`\mathrm{\mathbb{blackboard}}`
-#     ``\mathfrak{Fraktur}``                 :math-stix:`\mathfrak{Fraktur}`
-#     ``\mathsf{sansserif}``                 :math-stix:`\mathsf{sansserif}`
-#     ``\mathrm{\mathsf{sansserif}}``        :math-stix:`\mathrm{\mathsf{sansserif}}`
-#     ====================================== =========================================
-#
-#   .. htmlonly::
-#
-#     ====================================== =========================================
-#     ``\mathcircled{circled}``              :math-stix:`\mathcircled{circled}`
-#     ====================================== =========================================
-#
-# There are also three global "font sets" to choose from, which are
-# selected using the ``mathtext.fontset`` parameter in
-# :ref:`matplotlibrc <matplotlibrc-sample>`.
-#
-# ``cm``: **Computer Modern (TeX)**
-#
-# .. image:: ../../_static/cm_fontset.png
-#
-# ``stix``: **STIX** (designed to blend well with Times)
-#
-# .. image:: ../../_static/stix_fontset.png
-#
-# ``stixsans``: **STIX sans-serif**
-#
-# .. image:: ../../_static/stixsans_fontset.png
-#
-# Additionally, you can use ``\mathdefault{...}`` or its alias
-# ``\mathregular{...}`` to use the font used for regular text outside of
-# mathtext.  There are a number of limitations to this approach, most
-# notably that far fewer symbols will be available, but it can be useful
-# to make math expressions blend well with other text in the plot.
-#
-# Custom fonts
-# ~~~~~~~~~~~~
-#
-# mathtext also provides a way to use custom fonts for math.  This
-# method is fairly tricky to use, and should be considered an
-# experimental feature for patient users only.  By setting the rcParam
-# ``mathtext.fontset`` to ``custom``, you can then set the following
-# parameters, which control which font file to use for a particular set
-# of math characters.
-#
-#     ============================== =================================
-#     Parameter                      Corresponds to
-#     ============================== =================================
-#     ``mathtext.it``                ``\mathit{}`` or default italic
-#     ``mathtext.rm``                ``\mathrm{}`` Roman (upright)
-#     ``mathtext.tt``                ``\mathtt{}`` Typewriter (monospace)
-#     ``mathtext.bf``                ``\mathbf{}`` bold italic
-#     ``mathtext.cal``               ``\mathcal{}`` calligraphic
-#     ``mathtext.sf``                ``\mathsf{}`` sans-serif
-#     ============================== =================================
-#
-# Each parameter should be set to a fontconfig font descriptor (as
-# defined in the yet-to-be-written font chapter).
-#
-# .. TODO: Link to font chapter
-#
-# The fonts used should have a Unicode mapping in order to find any
-# non-Latin characters, such as Greek.  If you want to use a math symbol
-# that is not contained in your custom fonts, you can set the rcParam
-# ``mathtext.fallback_to_cm`` to ``True`` which will cause the mathtext
-# system to use characters from the default Computer Modern fonts
-# whenever a particular character can not be found in the custom font.
-#
-# Note that the math glyphs specified in Unicode have evolved over time,
-# and many fonts may not have glyphs in the correct place for mathtext.
-#
-# Accents
-# -------
-#
-# An accent command may precede any symbol to add an accent above it.
-# There are long and short forms for some of them.
-#
-#     ============================== =================================
-#     Command                        Result
-#     ============================== =================================
-#     ``\acute a`` or ``\'a``        :math:`\acute a`
-#     ``\bar a``                     :math:`\bar a`
-#     ``\breve a``                   :math:`\breve a`
-#     ``\ddot a`` or ``\''a``        :math:`\ddot a`
-#     ``\dot a`` or ``\.a``          :math:`\dot a`
-#     ``\grave a`` or ``\`a``        :math:`\grave a`
-#     ``\hat a`` or ``\^a``          :math:`\hat a`
-#     ``\tilde a`` or ``\~a``        :math:`\tilde a`
-#     ``\vec a``                     :math:`\vec a`
-#     ``\overline{abc}``             :math:`\overline{abc}`
-#     ============================== =================================
-#
-# In addition, there are two special accents that automatically adjust
-# to the width of the symbols below:
-#
-#     ============================== =================================
-#     Command                        Result
-#     ============================== =================================
-#     ``\widehat{xyz}``              :math:`\widehat{xyz}`
-#     ``\widetilde{xyz}``            :math:`\widetilde{xyz}`
-#     ============================== =================================
-#
-# Care should be taken when putting accents on lower-case i's and j's.
-# Note that in the following ``\imath`` is used to avoid the extra dot
-# over the i::
-#
-#     r"$\hat i\ \ \hat \imath$"
-#
-# .. math::
-#
-#     \hat i\ \ \hat \imath
-#
-# Symbols
-# -------
-#
-# You can also use a large number of the TeX symbols, as in ``\infty``,
-# ``\leftarrow``, ``\sum``, ``\int``.
-#
-# .. math_symbol_table::
-#
-# If a particular symbol does not have a name (as is true of many of the
-# more obscure symbols in the STIX fonts), Unicode characters can
-# also be used::
-#
-#    ur'$\u23ce$'
-#
-# Example
-# -------
-#
-# Here is an example illustrating many of these features in context.
-#
-# .. figure:: ../../gallery/pyplots/images/sphx_glr_pyplot_mathtext_001.png
-#    :target: ../../gallery/pyplots/pyplot_mathtext.html
-#    :align: center
-#    :scale: 50
-#
-#    Pyplot Mathtext
+   This default can be changed using the ``mathtext.default`` rcParam.  This is
+   useful, for example, to use the same font as regular non-math text for math
+   text, by setting it to ``regular``.
+
+To change fonts, e.g., to write "sin" in a Roman font, enclose the text in a
+font command::
+
+    r'$s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)$'
+
+.. math::
+
+    s(t) = \mathcal{A}\mathrm{sin}(2 \omega t)
+
+More conveniently, many commonly used function names that are typeset in
+a Roman font have shortcuts.  So the expression above could be written as
+follows::
+
+    r'$s(t) = \mathcal{A}\sin(2 \omega t)$'
+
+.. math::
+
+    s(t) = \mathcal{A}\sin(2 \omega t)
+
+Here "s" and "t" are variable in italics font (default), "sin" is in Roman
+font, and the amplitude "A" is in calligraphy font.  Note in the example above
+the calligraphy ``A`` is squished into the ``sin``.  You can use a spacing
+command to add a little whitespace between them::
+
+    r's(t) = \mathcal{A}\/\sin(2 \omega t)'
+
+.. math::
+
+    s(t) = \mathcal{A}\/\sin(2 \omega t)
+
+The choices available with all fonts are:
+
+    ========================= ================================
+    Command                   Result
+    ========================= ================================
+    ``\mathrm{Roman}``        :mathmpl:`\mathrm{Roman}`
+    ``\mathit{Italic}``       :mathmpl:`\mathit{Italic}`
+    ``\mathtt{Typewriter}``   :mathmpl:`\mathtt{Typewriter}`
+    ``\mathcal{CALLIGRAPHY}`` :mathmpl:`\mathcal{CALLIGRAPHY}`
+    ========================= ================================
+
+.. role:: math-stix(mathmpl)
+   :fontset: stix
+
+When using the `STIX <http://www.stixfonts.org/>`_ fonts, you also have the
+choice of:
+
+    ================================ =========================================
+    Command                          Result
+    ================================ =========================================
+    ``\mathbb{blackboard}``          :math-stix:`\mathbb{blackboard}`
+    ``\mathrm{\mathbb{blackboard}}`` :math-stix:`\mathrm{\mathbb{blackboard}}`
+    ``\mathfrak{Fraktur}``           :math-stix:`\mathfrak{Fraktur}`
+    ``\mathsf{sansserif}``           :math-stix:`\mathsf{sansserif}`
+    ``\mathrm{\mathsf{sansserif}}``  :math-stix:`\mathrm{\mathsf{sansserif}}`
+    ================================ =========================================
+
+  .. only:: html
+
+    ================================ =========================================
+    ``\mathcircled{circled}``        :math-stix:`\mathcircled{circled}`
+    ================================ =========================================
+
+There are also three global "font sets" to choose from, which are
+selected using the ``mathtext.fontset`` parameter in :ref:`matplotlibrc
+<matplotlibrc-sample>`.
+
+``cm``: **Computer Modern (TeX)**
+
+.. image:: ../../_static/cm_fontset.png
+
+``stix``: **STIX** (designed to blend well with Times)
+
+.. image:: ../../_static/stix_fontset.png
+
+``stixsans``: **STIX sans-serif**
+
+.. image:: ../../_static/stixsans_fontset.png
+
+Additionally, you can use ``\mathdefault{...}`` or its alias
+``\mathregular{...}`` to use the font used for regular text outside of
+mathtext.  There are a number of limitations to this approach, most notably
+that far fewer symbols will be available, but it can be useful to make math
+expressions blend well with other text in the plot.
+
+Custom fonts
+~~~~~~~~~~~~
+
+mathtext also provides a way to use custom fonts for math.  This method is
+fairly tricky to use, and should be considered an experimental feature for
+patient users only.  By setting the rcParam ``mathtext.fontset`` to ``custom``,
+you can then set the following parameters, which control which font file to use
+for a particular set of math characters.
+
+    ============================== =================================
+    Parameter                      Corresponds to
+    ============================== =================================
+    ``mathtext.it``                ``\mathit{}`` or default italic
+    ``mathtext.rm``                ``\mathrm{}`` Roman (upright)
+    ``mathtext.tt``                ``\mathtt{}`` Typewriter (monospace)
+    ``mathtext.bf``                ``\mathbf{}`` bold italic
+    ``mathtext.cal``               ``\mathcal{}`` calligraphic
+    ``mathtext.sf``                ``\mathsf{}`` sans-serif
+    ============================== =================================
+
+Each parameter should be set to a fontconfig font descriptor (as defined in the
+yet-to-be-written font chapter).
+
+.. TODO: Link to font chapter
+
+The fonts used should have a Unicode mapping in order to find any
+non-Latin characters, such as Greek.  If you want to use a math symbol
+that is not contained in your custom fonts, you can set the rcParam
+``mathtext.fallback_to_cm`` to ``True`` which will cause the mathtext system
+to use characters from the default Computer Modern fonts whenever a particular
+character can not be found in the custom font.
+
+Note that the math glyphs specified in Unicode have evolved over time, and many
+fonts may not have glyphs in the correct place for mathtext.
+
+Accents
+-------
+
+An accent command may precede any symbol to add an accent above it.  There are
+long and short forms for some of them.
+
+    ============================== =================================
+    Command                        Result
+    ============================== =================================
+    ``\acute a`` or ``\'a``        :mathmpl:`\acute a`
+    ``\bar a``                     :mathmpl:`\bar a`
+    ``\breve a``                   :mathmpl:`\breve a`
+    ``\ddot a`` or ``\''a``        :mathmpl:`\ddot a`
+    ``\dot a`` or ``\.a``          :mathmpl:`\dot a`
+    ``\grave a`` or ``\`a``        :mathmpl:`\grave a`
+    ``\hat a`` or ``\^a``          :mathmpl:`\hat a`
+    ``\tilde a`` or ``\~a``        :mathmpl:`\tilde a`
+    ``\vec a``                     :mathmpl:`\vec a`
+    ``\overline{abc}``             :mathmpl:`\overline{abc}`
+    ============================== =================================
+
+In addition, there are two special accents that automatically adjust to the
+width of the symbols below:
+
+    ============================== =================================
+    Command                        Result
+    ============================== =================================
+    ``\widehat{xyz}``              :mathmpl:`\widehat{xyz}`
+    ``\widetilde{xyz}``            :mathmpl:`\widetilde{xyz}`
+    ============================== =================================
+
+Care should be taken when putting accents on lower-case i's and j's.  Note that
+in the following ``\imath`` is used to avoid the extra dot over the i::
+
+    r"$\hat i\ \ \hat \imath$"
+
+.. math::
+
+    \hat i\ \ \hat \imath
+
+Symbols
+-------
+
+You can also use a large number of the TeX symbols, as in ``\infty``,
+``\leftarrow``, ``\sum``, ``\int``.
+
+.. math_symbol_table::
+
+If a particular symbol does not have a name (as is true of many of the more
+obscure symbols in the STIX fonts), Unicode characters can also be used::
+
+   ur'$\u23ce$'
+
+Example
+-------
+
+Here is an example illustrating many of these features in context.
+
+.. figure:: ../../gallery/pyplots/images/sphx_glr_pyplot_mathtext_001.png
+   :target: ../../gallery/pyplots/pyplot_mathtext.html
+   :align: center
+   :scale: 50
+
+   Pyplot Mathtext
+"""