Make plot_directive use a custom PlotWarning category.

fperez · fperez · commit b61448cf2e79 · 2010-02-04T04:58:51.000Z
svn path=/trunk/matplotlib/; revision=8110
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,6 @@
+2010-02-03 Made plot_directive use a custom PlotWarning category, so that
+           warnings can be turned into fatal errors easily if desired. - FP
+
 2010-01-29 Added draggable method to Legend to allow mouse drag
 placement.  Thanks Adam Fraser. JDH
 
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -44,6 +44,18 @@
 
 The set of file formats to generate can be specified with the
 `plot_formats` configuration variable.
+
+
+Error handling:
+
+Any errors generated during the running of the code are emitted as warnings
+using the Python `warnings` module, using a custom category called
+`PlotWarning`.  To turn the warnings into fatal errors that stop the
+documentation build, after adjusting your `sys.path` in your `conf.py` Sphinx
+configuration file, use::
+
+    import plot_directive
+    warnings.simplefilter('error', plot_directive.PlotWarning)
 """
 
 import sys, os, shutil, imp, warnings, cStringIO, re
@@ -76,6 +88,21 @@
 from matplotlib import _pylab_helpers
 from matplotlib.sphinxext import only_directives
 
+
+class PlotWarning(Warning):
+    """Warning category for all warnings generated by this directive.
+
+    By printing our warnings with this category, it becomes possible to turn
+    them into errors by using in your conf.py::
+
+      warnings.simplefilter('error', plot_directive.PlotWarning)
+
+    This way, you can ensure that your docs only build if all your examples
+    actually run successfully.
+    """
+    pass
+
+
 # os.path.relpath is new in Python 2.6
 if hasattr(os.path, 'relpath'):
     relpath = os.path.relpath
@@ -208,7 +235,7 @@ def run_savefig(plot_path, basename, tmpdir, destdir, formats):
                 figman.canvas.figure.savefig(outpath, dpi=dpi)
             except:
                 s = cbook.exception_to_str("Exception saving plot %s" % plot_path)
-                warnings.warn(s)
+                warnings.warn(s, PlotWarning)
                 return 0
             if j > 0:
                 shutil.copyfile(outpath, os.path.join(destdir, outname))
@@ -270,7 +297,7 @@ def render_figures(plot_path, function_name, plot_code, tmpdir, destdir,
         run_code(plot_path, function_name, plot_code)
     except:
         s = cbook.exception_to_str("Exception running plot %s" % plot_path)
-        warnings.warn(s)
+        warnings.warn(s, PlotWarning)
         return 0
 
     num_figs = run_savefig(plot_path, basename, tmpdir, destdir, formats)
