matplotlib · tacaswell · Sep 15, 2018 · Sep 15, 2018
diff --git 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/users/next_whats_new/2018-09-15-AL.rst 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
@@ -1,10 +1,11 @@
+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
@@ -70,7 +71,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):
@@ -119,9 +120,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
@@ -44,7 +44,7 @@
 #     # math text
 #     plt.title(r'$\alpha > \beta$')
 #
-# produces ":math:`\alpha > \beta`".
+# produces ":mathmpl:`\alpha > \beta`".
 #
 # .. note::
 #    Mathtext should be placed between a pair of dollar signs ($).  To
@@ -77,9 +77,9 @@
 #
 #     \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::
+# 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$'
 #
@@ -200,13 +200,13 @@
 #     ============================ ==================================
 #     Command                      Result
 #     ============================ ==================================
-#     ``\mathrm{Roman}``           :math:`\mathrm{Roman}`
-#     ``\mathit{Italic}``          :math:`\mathit{Italic}`
-#     ``\mathtt{Typewriter}``      :math:`\mathtt{Typewriter}`
-#     ``\mathcal{CALLIGRAPHY}``    :math:`\mathcal{CALLIGRAPHY}`
+#     ``\mathrm{Roman}``           :mathmpl:`\mathrm{Roman}`
+#     ``\mathit{Italic}``          :mathmpl:`\mathit{Italic}`
+#     ``\mathtt{Typewriter}``      :mathmpl:`\mathtt{Typewriter}`
+#     ``\mathcal{CALLIGRAPHY}``    :mathmpl:`\mathcal{CALLIGRAPHY}`
 #     ============================ ==================================
 #
-# .. role:: math-stix(math)
+# .. role:: math-stix(mathmpl)
 #    :fontset: stix
 #
 # When using the `STIX <http://www.stixfonts.org/>`_ fonts, you also have the choice of:
@@ -294,16 +294,16 @@
 #     ============================== =================================
 #     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}`
+#     ``\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
@@ -312,8 +312,8 @@
 #     ============================== =================================
 #     Command                        Result
 #     ============================== =================================
-#     ``\widehat{xyz}``              :math:`\widehat{xyz}`
-#     ``\widetilde{xyz}``            :math:`\widetilde{xyz}`
+#     ``\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.