matplotlib · dstansby · Feb 12, 2019 · Sep 7, 2018 · Sep 18, 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/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
@@ -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
@@ -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,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