Merge pull request #13781 from meeseeksmachine/auto-backport-of-pr-13777-on-v3.1.x

QuLogic · web-flow · commit edc35fd5bde3 · 2019-03-29T05:17:26.000-04:00
Backport PR #13777 on branch v3.1.x (Use class-based directive for mathmpl sphinxext.)
diff --git a/doc/api/next_api_changes/2019-01-09-deprecations.rst b/doc/api/next_api_changes/2019-01-09-deprecations.rst
@@ -1,8 +1,10 @@
 Deprecations
 ````````````
 
-The ``matplotlib.sphinxext.plot_directive`` interface has changed from
-the (Sphinx-)deprecated function-based interface to a class-based interface.
-This should not affect end users, but the
-``matplotlib.sphinxext.plot_directive.plot_directive`` function is now
+The ``matplotlib.sphinxext.mathmpl`` and
+``matplotlib.sphinxext.plot_directive`` interfaces have changed from the
+(Sphinx-)deprecated function-based interface to a class-based interface.  This
+should not affect end users, but the
+``matplotlib.sphinxext.mathmpl.math_directive`` and
+``matplotlib.sphinxext.plot_directive.plot_directive`` functions are now
 deprecated.
diff --git a/lib/matplotlib/sphinxext/mathmpl.py b/lib/matplotlib/sphinxext/mathmpl.py
@@ -3,7 +3,7 @@
 import sys
 
 from docutils import nodes
-from docutils.parsers.rst import directives
+from docutils.parsers.rst import Directive, directives
 import sphinx
 
 from matplotlib import rcParams
@@ -22,9 +22,6 @@ def fontset_choice(arg):
     return directives.choice(arg, ['cm', 'stix', 'stixsans'])
 
 
-options_spec = {'fontset': fontset_choice}
-
-
 def math_role(role, rawtext, text, lineno, inliner,
               options={}, content=[]):
     i = rawtext.find('`')
@@ -33,11 +30,10 @@ def math_role(role, rawtext, text, lineno, inliner,
     node['latex'] = latex
     node['fontset'] = options.get('fontset', 'cm')
     return [node], []
+math_role.options = {'fontset': fontset_choice}
 
 
-math_role.options = options_spec
-
-
+@cbook.deprecated("3.1", alternative="MathDirective")
 def math_directive(name, arguments, options, content, lineno,
                    content_offset, block_text, state, state_machine):
     latex = ''.join(content)
@@ -47,6 +43,21 @@ def math_directive(name, arguments, options, content, lineno,
     return [node]
 
 
+class MathDirective(Directive):
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {'fontset': fontset_choice}
+
+    def run(self):
+        latex = ''.join(self.content)
+        node = latex_math(self.block_text)
+        node['latex'] = latex
+        node['fontset'] = self.options.get('fontset', 'cm')
+        return [node]
+
+
 # This uses mathtext to render the expression
 def latex2png(latex, filename, fontset='cm'):
     latex = "$%s$" % latex
@@ -121,12 +132,10 @@ def depart_latex_math_latex(self, node):
                  html=(visit_latex_math_html, depart_latex_math_html),
                  latex=(visit_latex_math_latex, depart_latex_math_latex))
     app.add_role('mathmpl', math_role)
-    app.add_directive('mathmpl', math_directive,
-                      True, (0, 0, 0), **options_spec)
+    app.add_directive('mathmpl', MathDirective)
     if sphinx.version_info < (1, 8):
         app.add_role('math', math_role)
-        app.add_directive('math', math_directive,
-                          True, (0, 0, 0), **options_spec)
+        app.add_directive('math', MathDirective)
 
     metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
     return metadata
