Improve multipage pdf documentation

jkseppan · jkseppan · commit 319a78ecd667 · 2009-08-30T10:33:01.000Z
svn path=/trunk/matplotlib/; revision=7597
diff --git a/doc/api/backend_pdf_api.rst b/doc/api/backend_pdf_api.rst
@@ -0,0 +1,7 @@
+
+:mod:`matplotlib.backends.backend_pdf`
+======================================
+
+.. automodule:: matplotlib.backends.backend_pdf
+   :members:
+   :show-inheritance:
diff --git a/doc/api/index_backend_api.rst b/doc/api/index_backend_api.rst
@@ -8,5 +8,6 @@ matplotlib backends
    backend_gtkagg_api.rst
    backend_qt4agg_api.rst
    backend_wxagg_api.rst
+   backend_pdf_api.rst
    dviread.rst
    type1font.rst
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -68,6 +68,35 @@ on individual elements, eg::
    ax.set_xlabel('volts', alpha=0.5)
 
 
+.. _howto-multipage:
+
+Save multiple plots in one pdf file
+-----------------------------------
+
+Many image file formats can only have one image per file, but some
+formats support multi-page files. Currently only the pdf backend has
+support for this. To make a multi-page pdf file, first initialize the
+file::
+
+    from matplotlib.backends.backend_pdf import PdfPages
+    pp = PdfPages('multipage.pdf')
+
+You can give the :class:`~matplotlib.backends.backend_pdf.PdfPages`
+object to :func:`~matplotlib.pyplot.savefig`, but you have to specify
+the format::
+
+    savefig(pp, format='pdf')
+
+A simpler way is to call
+:meth:`PdfPages.savefig <matplotlib.backends.backend_pdf.PdfPages.savefig>`::
+
+    pp.savefig()
+
+Finally, the multipage pdf object has to be closed::
+
+    pp.close()
+
+
 .. _howto-subplots-adjust:
 
 Move the edge of an axes to make room for tick labels
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -348,7 +348,7 @@ def _flush(self):
             self.compressobj = None
 
 class PdfFile(object):
-    """PDF file with one page."""
+    """PDF file object."""
 
     def __init__(self, filename):
         self.nextObject = 1     # next free object id
@@ -1923,18 +1923,18 @@ class PdfPages(object):
     """
     A multi-page PDF file.
 
-    Use like this:
+    Use like this::
 
-      # Initialize:
-      pdf_pages = PdfPages('foo.pdf')
+        # Initialize:
+        pp = PdfPages('foo.pdf')
 
-      # As many times as you like, create a figure fig, then either:
-      fig.savefig(pdf_pages, format='pdf') # note the format argument!
-      # or:
-      pdf_pages.savefig(fig)
+        # As many times as you like, create a figure fig, then either:
+        fig.savefig(pp, format='pdf') # note the format argument!
+        # or:
+        pp.savefig(fig)
 
-      # Once you are done, remember to close the object:
-      pdf_pages.close()
+        # Once you are done, remember to close the object:
+        pp.close()
 
     (In reality PdfPages is a thin wrapper around PdfFile, in order to
     avoid confusion when using savefig and forgetting the format
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -981,10 +981,14 @@ def savefig(self, *args, **kwargs):
         Arguments:
 
           *fname*:
-            A string containing a path to a filename, or a Python file-like object.
+            A string containing a path to a filename, or a Python file-like object,
+            or possibly some backend-dependent object such as
+            :class:`~matplotlib.backends.backend_pdf.PdfPages`.
 
             If *format* is *None* and *fname* is a string, the output
             format is deduced from the extension of the filename.
+            If *fname* is not a string, remember to specify *format* to
+            ensure that the correct backend is used.
 
         Keyword arguments:
 
