diff --git a/doc-requirements.txt b/doc-requirements.txt
index d9e3e3ef79c7..446ed9d980da 100644
--- a/doc-requirements.txt
+++ b/doc-requirements.txt
@@ -6,7 +6,7 @@
# Install the documentation requirements with:
# pip install -r doc-requirements.txt
#
-sphinx>=1.3,!=1.5.0,!=1.6.4,!=1.7.3,<1.8
+sphinx>=1.3,!=1.5.0,!=1.6.4,!=1.7.3
colorspacious
ipython
ipywidgets
diff --git a/doc/conf.py b/doc/conf.py
index 4b4b5ed5f383..017ce210e372 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -22,6 +22,7 @@
# 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 @@
'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 @@ def _check_deps():
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 = {
'python': ('https://docs.python.org/3', None),
diff --git a/doc/sphinxext/github.py b/doc/sphinxext/github.py
index 8f0ffc0d9782..75c5ce10ae9d 100644
--- a/doc/sphinxext/github.py
+++ b/doc/sphinxext/github.py
@@ -75,7 +75,6 @@ def ghissue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
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, lineno, inliner, options={}, content=[]):
: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, lineno, inliner, options={}, content=[]):
: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)
diff --git a/doc/users/next_whats_new/2018-09-15-AL.rst b/doc/users/next_whats_new/2018-09-15-AL.rst
new file mode 100644
index 000000000000..863d2f2b005b
--- /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.
diff --git a/lib/matplotlib/sphinxext/mathmpl.py b/lib/matplotlib/sphinxext/mathmpl.py
index 26968cb03e54..4bfbc52a2491 100644
--- 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='cm'):
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 depart_latex_math_latex(self, node):
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
diff --git a/tutorials/text/mathtext.py b/tutorials/text/mathtext.py
index de1a32f20aa1..96a523f192cf 100644
--- 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 `_ 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 ` 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 `_ 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" `_ 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
-# `_.
-#
-# 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
-# ` 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 `_ 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 `.
-#
-# ``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 `_ 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
+`.
+
+``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
+"""