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

[<jo...@us...>]

Revision: 7597
          http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7597&view=rev
Author:   jouni
Date:     2009-08-30 10:33:01 +0000 (Sun, 30 Aug 2009)

Log Message:
-----------
Improve multipage pdf documentation

Modified Paths:
--------------
    trunk/matplotlib/doc/api/index_backend_api.rst
    trunk/matplotlib/doc/faq/howto_faq.rst
    trunk/matplotlib/lib/matplotlib/backends/backend_pdf.py
    trunk/matplotlib/lib/matplotlib/figure.py

Added Paths:
-----------
    trunk/matplotlib/doc/api/backend_pdf_api.rst

Added: trunk/matplotlib/doc/api/backend_pdf_api.rst
===================================================================
--- trunk/matplotlib/doc/api/backend_pdf_api.rst	                        (rev 0)
+++ trunk/matplotlib/doc/api/backend_pdf_api.rst	2009-08-30 10:33:01 UTC (rev 7597)
@@ -0,0 +1,7 @@
+
+:mod:`matplotlib.backends.backend_pdf`
+======================================
+
+.. automodule:: matplotlib.backends.backend_pdf
+   :members:
+   :show-inheritance:

Modified: trunk/matplotlib/doc/api/index_backend_api.rst
===================================================================
--- trunk/matplotlib/doc/api/index_backend_api.rst	2009-08-30 06:29:58 UTC (rev 7596)
+++ trunk/matplotlib/doc/api/index_backend_api.rst	2009-08-30 10:33:01 UTC (rev 7597)
@@ -8,5 +8,6 @@
    backend_gtkagg_api.rst
    backend_qt4agg_api.rst
    backend_wxagg_api.rst
+   backend_pdf_api.rst
    dviread.rst
    type1font.rst

Modified: trunk/matplotlib/doc/faq/howto_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/howto_faq.rst	2009-08-30 06:29:58 UTC (rev 7596)
+++ trunk/matplotlib/doc/faq/howto_faq.rst	2009-08-30 10:33:01 UTC (rev 7597)
@@ -68,6 +68,35 @@
    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

Modified: trunk/matplotlib/lib/matplotlib/backends/backend_pdf.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/backends/backend_pdf.py	2009-08-30 06:29:58 UTC (rev 7596)
+++ trunk/matplotlib/lib/matplotlib/backends/backend_pdf.py	2009-08-30 10:33:01 UTC (rev 7597)
@@ -348,7 +348,7 @@
             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 @@
     """
     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

Modified: trunk/matplotlib/lib/matplotlib/figure.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/figure.py	2009-08-30 06:29:58 UTC (rev 7596)
+++ trunk/matplotlib/lib/matplotlib/figure.py	2009-08-30 10:33:01 UTC (rev 7597)
@@ -981,10 +981,14 @@
         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:
 


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