Merge pull request #13138 from larsoner/plot_directive

anntzer · web-flow · commit 8466da0a1201 · 2019-01-10T10:58:54.000+01:00
API: Use class-based directive in sphinxext
diff --git a/.flake8 b/.flake8
@@ -42,7 +42,6 @@ per-file-ignores =
     matplotlib/projections/geo.py: E203, E221, E502
     matplotlib/pylab.py: E501
     matplotlib/rcsetup.py: E501
-    matplotlib/sphinxext/plot_directive.py: E402
     matplotlib/tests/test_mathtext.py: E501
     matplotlib/transforms.py: E201, E202, E203, E501
     matplotlib/tri/triinterpolate.py: E201, E221
diff --git a/doc/api/next_api_changes/2019-01-09-deprecations.rst b/doc/api/next_api_changes/2019-01-09-deprecations.rst
@@ -0,0 +1,8 @@
+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
+deprecated.
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -148,9 +148,8 @@
 import traceback
 import warnings
 
-from docutils.parsers.rst import directives
+from docutils.parsers.rst import directives, Directive
 from docutils.parsers.rst.directives.images import Image
-align = Image.align
 import jinja2  # Sphinx dependency.
 
 import matplotlib
@@ -165,6 +164,7 @@
 else:
     import matplotlib.pyplot as plt
 from matplotlib import _pylab_helpers, cbook
+align = Image.align
 
 __version__ = 2
 
@@ -174,6 +174,7 @@
 # -----------------------------------------------------------------------------
 
 
+@cbook.deprecated("3.1", alternative="PlotDirective")
 def plot_directive(name, arguments, options, content, lineno,
                    content_offset, block_text, state, state_machine):
     """Implementation of the ``.. plot::`` directive.
@@ -241,25 +242,42 @@ def mark_plot_labels(app, document):
                     break
 
 
+class PlotDirective(Directive):
+    """Implementation of the ``.. plot::`` directive.
+
+    See the module docstring for details.
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 2
+    final_argument_whitespace = False
+    option_spec = {
+        'alt': directives.unchanged,
+        'height': directives.length_or_unitless,
+        'width': directives.length_or_percentage_or_unitless,
+        'scale': directives.nonnegative_int,
+        'align': _option_align,
+        'class': directives.class_option,
+        'include-source': _option_boolean,
+        'format': _option_format,
+        'context': _option_context,
+        'nofigs': directives.flag,
+        'encoding': directives.encoding,
+        }
+
+    def run(self):
+        """Run the plot directive."""
+        return run(self.arguments, self.content, self.options,
+                   self.state_machine, self.state, self.lineno)
+
+
 def setup(app):
+    import matplotlib
     setup.app = app
     setup.config = app.config
     setup.confdir = app.confdir
-
-    options = {'alt': directives.unchanged,
-               'height': directives.length_or_unitless,
-               'width': directives.length_or_percentage_or_unitless,
-               'scale': directives.nonnegative_int,
-               'align': _option_align,
-               'class': directives.class_option,
-               'include-source': _option_boolean,
-               'format': _option_format,
-               'context': _option_context,
-               'nofigs': directives.flag,
-               'encoding': directives.encoding
-               }
-
-    app.add_directive('plot', plot_directive, True, (0, 2, False), **options)
+    app.add_directive('plot', PlotDirective)
     app.add_config_value('plot_pre_code', None, True)
     app.add_config_value('plot_include_source', False, True)
     app.add_config_value('plot_html_show_source_link', True, True)
@@ -273,7 +291,8 @@ def setup(app):
 
     app.connect('doctree-read', mark_plot_labels)
 
-    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
+    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True,
+                'version': matplotlib.__version__}
     return metadata
 
 
