Refining the matplotlib APIs in IPython.display.

IPython/core/display.py

@@ -24,7 +24,7 b' import struct'
 
 from IPython.utils.py3compat import (string_types, cast_bytes_py2, cast_unicode,
                                      unicode_type)
-
+from IPython.testing.skipdoctest import skip_doctest
 from .displaypub import publish_display_data
 
 #-----------------------------------------------------------------------------
@@ -719,18 +719,53 b' def clear_output(wait=False):'
         io.stderr.flush()
 
 
-def select_matplotlib_formats(formats, quality=90):
-    """Select figure formats for the inline backend.
+@skip_doctest
+def set_matplotlib_formats(*formats, **kwargs):
+    """Select figure formats for the inline backend. Optionally pass quality for JPEG.
+
+    For example, this enables PNG and JPEG output with a JPEG quality of 90%::
+
+        In [1]: set_matplotlib_formats('png', 'jpeg', quality=90)
+
+    To set this in your config files use the following::
+    
+        c.InlineBackend.figure_formats = {'pdf', 'png', 'svg'}
 
     Parameters
-    ==========
-    formats : list
+    ----------
+    *formats : list, tuple
         One or a set of figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
     quality : int
-        A percentage for the quality of JPEG figures.
+        A percentage for the quality of JPEG figures. Defaults to 90.
     """
     from IPython.core.interactiveshell import InteractiveShell
     from IPython.core.pylabtools import select_figure_formats
     shell = InteractiveShell.instance()
     select_figure_formats(shell, formats, quality=90)
 
+@skip_doctest
+def set_matplotlib_close(close):
+    """Should the inline backend close all figures automatically.
+    
+    By default, the inline backend used in the IPython Notebook will close all
+    matplotlib figures automatically after each cell is run. This means that
+    plots in different cells won't interfere. Sometimes, you may want to make
+    a plot in one cell and then refine it in later cells. This can be accomplished
+    by::
+    
+        In [1]: set_matplotlib_close(False)
+    
+    To set this in your config files use the following::
+    
+        c.InlineBackend.close_figures = False
+    
+    Parameters
+    ----------
+    close : bool
+        Should all matplotlib figures be automatically closed after each cell is
+        run?
+    """
+    from IPython.kernel.zmq.pylab.backend_inline import InlineBackend
+    ilbe = InlineBackend.instance()
+    ilbe.close_figures = close
+

IPython/core/magics/pylab.py

@@ -47,28 +47,32 b' class PylabMagics(Magics):'
         """Set up matplotlib to work interactively.
         
         This function lets you activate matplotlib interactive support
-        at any point during an IPython session.
-        It does not import anything into the interactive namespace.
+        at any point during an IPython session. It does not import anything
+        into the interactive namespace.
         
-        If you are using the inline matplotlib backend for embedded figures,
-        you can adjust its behavior via the %config magic::
+        If you are using the inline matplotlib backend in the IPython Notebook
+        you can set which figure formats are enabled using the following::
 
-            # enable SVG figures, necessary for SVG+XHTML export in the qtconsole
-            In [1]: %config InlineBackend.figure_format = 'svg'
+            In [1]: from IPython.display import set_matplotlib_formats
 
-            # change the behavior of closing all figures at the end of each
-            # execution (cell), or allowing reuse of active figures across
-            # cells:
-            In [2]: %config InlineBackend.close_figures = False
+            In [2]: set_matplotlib_formats('pdf', 'svg')
+
+        See the docstring of `IPython.display.set_matplotlib_formats` and
+        `IPython.display.set_matplotlib_close` for more information on
+        changing the behavior of the inline backend.
 
         Examples
         --------
-        In this case, where the MPL default is TkAgg::
+        To enable the inline backend for usage with the IPython Notebook::
+        
+            In [1]: %matplotlib inline
+
+        In this case, where the matplotlib default is TkAgg::
 
             In [2]: %matplotlib
             Using matplotlib backend: TkAgg
 
-        But you can explicitly request a different backend::
+        But you can explicitly request a different GUI backend::
 
             In [3]: %matplotlib qt
         """