Merge pull request #2913 from astrofrog/reset-context-plot-directive

tacaswell · tacaswell · commit a429c415bdb6 · 2014-04-16T21:05:03.000-04:00
Allow :context: directive to take 'reset' option. Fixes #2892.
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -241,6 +241,14 @@ url as a link in output SVGs.  This allows one to make clickable text in
 saved figures using the url kwarg of the :class:`~matplotlib.text.Text`
 class.
 
+Sphinx extensions
+-----------------
+
+The ``:context:`` directive in the `~matplotlib.sphinxext.plot_directive`
+Sphinx extension can now accept an optional ``reset`` setting, which will
+cause the context to be reset. This allows more than one distinct context to
+be present in documentation. To enable this option, use ``:context: reset``
+instead of ``:context:`` any time you want to reset the context.
 
 .. _whats-new-1-3:
 
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -58,11 +58,12 @@
         The encoding will not be inferred using the ``-*- coding -*-``
         metacomment.
 
-    context : bool
+    context : bool or str
         If provided, the code will be run in the context of all
         previous plot directives for which the `:context:` option was
         specified.  This only applies to inline code plot directives,
-        not those run from files.
+        not those run from files. If the ``:context: reset`` is specified,
+        the context is reset for this and future plots.
 
     nofigs : bool
         If specified, the code block will be run, but no figures will
@@ -249,9 +250,19 @@ def _option_boolean(arg):
     else:
         raise ValueError('"%s" unknown boolean' % arg)
 
+
+def _option_context(arg):
+    if arg in [None, 'reset']:
+        return arg
+    else:
+        raise ValueError("argument should be None or 'reset'")
+    return directives.choice(arg, ('None', 'reset'))
+
+
 def _option_format(arg):
     return directives.choice(arg, ('python', 'doctest'))
 
+
 def _option_align(arg):
     return directives.choice(arg, ("top", "middle", "bottom", "left", "center",
                                    "right"))
@@ -299,7 +310,7 @@ def setup(app):
                'class': directives.class_option,
                'include-source': _option_boolean,
                'format': _option_format,
-               'context': directives.flag,
+               'context': _option_context,
                'nofigs': directives.flag,
                'encoding': directives.encoding
                }
@@ -561,7 +572,7 @@ def clear_state(plot_rcparams, close=True):
     matplotlib.rcParams.update(plot_rcparams)
 
 def render_figures(code, code_path, output_dir, output_base, context,
-                   function_name, config):
+                   function_name, config, context_reset=False):
     """
     Run a pyplot script and save the low and high res PNGs and a PDF
     in outdir.
@@ -636,6 +647,8 @@ def render_figures(code, code_path, output_dir, output_base, context,
     else:
         ns = {}
 
+    if context_reset:
+        clear_state(config.plot_rcparams)
 
     for i, code_piece in enumerate(code_pieces):
 
@@ -680,6 +693,7 @@ def run(arguments, content, options, state_machine, state, lineno):
 
     options.setdefault('include-source', config.plot_include_source)
     context = 'context' in options
+    context_reset = True if (context and options['context'] == 'reset') else False
 
     rst_file = document.attributes['source']
     rst_dir = os.path.dirname(rst_file)
@@ -764,7 +778,8 @@ def run(arguments, content, options, state_machine, state, lineno):
     # make figures
     try:
         results = render_figures(code, source_file_name, build_dir, output_base,
-                                 context, function_name, config)
+                                 context, function_name, config,
+                                 context_reset=context_reset)
         errors = []
     except PlotError as err:
         reporter = state.memo.reporter
