SF.net SVN: matplotlib:[8110] trunk/matplotlib

[<fer...@us...>]

Revision: 8110
          http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8110&view=rev
Author:   fer_perez
Date:     2010-02-04 04:58:51 +0000 (Thu, 04 Feb 2010)

Log Message:
-----------
Make plot_directive use a custom PlotWarning category.

Modified Paths:
--------------
    trunk/matplotlib/CHANGELOG
    trunk/matplotlib/lib/matplotlib/sphinxext/plot_directive.py

Modified: trunk/matplotlib/CHANGELOG
===================================================================
--- trunk/matplotlib/CHANGELOG	2010-02-03 19:42:00 UTC (rev 8109)
+++ trunk/matplotlib/CHANGELOG	2010-02-04 04:58:51 UTC (rev 8110)
@@ -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
 

Modified: trunk/matplotlib/lib/matplotlib/sphinxext/plot_directive.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/sphinxext/plot_directive.py	2010-02-03 19:42:00 UTC (rev 8109)
+++ trunk/matplotlib/lib/matplotlib/sphinxext/plot_directive.py	2010-02-04 04:58:51 UTC (rev 8110)
@@ -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 @@
                 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 @@
         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)


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.