API: Use class-based directive in sphinxext

larsoner · larsoner · commit c153cfb35019 · 2019-01-09T14:00:45.000-05:00
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -148,7 +148,8 @@
 import traceback
 import warnings
 
-from docutils.parsers.rst import directives
+from docutils import nodes
+from docutils.parsers.rst import directives, Directive
 from docutils.parsers.rst.directives.images import Image
 align = Image.align
 import jinja2  # Sphinx dependency.
@@ -176,9 +177,10 @@
 
 def plot_directive(name, arguments, options, content, lineno,
                    content_offset, block_text, state, state_machine):
-    """Implementation of the ``.. plot::`` directive.
+    """Deprecated function-based implementation of the ``.. plot::`` directive.
 
-    See the module docstring for details.
+    Use PlotDirective instead.
+    See the module docstring for details on configuration.
     """
     return run(arguments, content, options, state_machine, state, lineno)
 
@@ -241,25 +243,45 @@ 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,
+                   function=False)
+
+
 def setup(app):
     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)
+    # Old, function-based method was equivalent to:
+    # app.add_directive('plot', plot_directive, True, (0, 2, False),
+    #                   **PlotDirective.option_spec)
+    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 +295,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': 0.2}
     return metadata
 
 
@@ -630,7 +653,8 @@ def render_figures(code, code_path, output_dir, output_base, context,
     return results
 
 
-def run(arguments, content, options, state_machine, state, lineno):
+def run(arguments, content, options, state_machine, state, lineno,
+        function=True):
     document = state_machine.document
     config = document.settings.env.config
     nofigs = 'nofigs' in options
@@ -800,9 +824,6 @@ def run(arguments, content, options, state_machine, state, lineno):
         total_lines.extend(result.split("\n"))
         total_lines.extend("\n")
 
-    if total_lines:
-        state_machine.insert_input(total_lines, source=source_file_name)
-
     # copy image files to builder's output directory, if necessary
     Path(dest_dir).mkdir(parents=True, exist_ok=True)
 
@@ -818,4 +839,14 @@ def run(arguments, content, options, state_machine, state, lineno):
         unescape_doctest(code) if source_file_name == rst_file else code,
         encoding='utf-8')
 
-    return errors
+    if function:
+        if total_lines:
+            state_machine.insert_input(total_lines, source=source_file_name)
+        out = errors
+    else:
+        if len(errors):
+            out = errors
+        else:
+            out = [nodes.raw('\n'.join(total_lines))] if total_lines else []
+
+    return out
