added auto subplots adj faq

svn path=/trunk/matplotlib/; revision=5596

Makefile

@@ -39,7 +39,7 @@ jdh_doc_snapshot:
 	rm -rf build;\
 	python make.py clean;\
 	svn up;\
-	python make.py html latex sf;
+	python make.py html latex sf sfpdf;
 
 
 

doc/faq/howto_faq.rst

@@ -54,6 +54,40 @@ where all values are in fractional (0 to 1) coordinates.  See
 `axes_demo.py <http://matplotlib.sf.net/examples/axes_demo.py>`_ for
 an example of placing axes manually.
 
+.. _howto-auto-adjust:
+
+How do I automatically make room for my tick labels?
+====================================================
+
+In most use cases, it is enought to simpy change the subplots adjust
+parameters as described in :ref:`howto-subplots-adjust`.  But in some
+cases, you don't know ahead of time what your tick labels will be, or
+how large they will be (data and labels outside your control may be
+being fed into your graphing application), and you may need to
+automatically adjust your subplot parameters based on the size of the
+tick labels.  Any :class:`matplotlib.text.Text` instance can report
+its extent in window coordinates (a negative x coordinate is outside
+the window), but there is a rub.
+
+The :class:`matplotlib.backend_bases.RendererBase` instance, which is
+used to calculate the text size, is not known until the figure is
+drawn (:meth:`matplotlib.figure.Figure.draw`).  After the window is
+drawn and the text instance knows its renderer, you can call
+:meth:`matplotlib.text.Text.get_window_extent``.  One way to solve
+this chicken and egg problem is to wait until the figure is draw by
+connecting
+(:meth:`matplotlib.backend_bases.FigureCanvasBase.mpl_connect`) to the
+"on_draw" signal (:class:`~matplotlib.backend_bases.DrawEvent`) and
+get the window extent there, and then do something with it, eg move
+the left of the canvas over; see :ref:`event-handling-tutorial`.
+
+Here is a recursive, iterative solution that will gradually move the
+left of the subplot over until the label fits w/o going outside the
+figure border (requires matplotlib 0.98)
+
+.. plot:: auto_subplots_adjust.py
+   :include-source:
+
 .. _howto-ticks:
 
 How do I configure the tick linewidths?

doc/glossary/index.rst

@@ -8,73 +8,138 @@ Glossary
 .. glossary::
 
   AGG
-      The Anti-Grain Geometry rendering engine, capable of rendering
-      high-quality images.
+      The Anti-Grain Geometry (`Agg <http://antigrain.com>`_) rendering engine, capable of rendering
+      high-quality images
 
   Cairo
-      The Cairo graphics engine
+      The `Cairo graphics <http://cairographics.org>`_ engine
 
   EPS
-      Encapsulated Postscript
+      Encapsulated Postscript (`EPS <http://en.wikipedia.org/wiki/Encapsulated_PostScript>`_)
 
   FLTK
-      FLTK (pronounced "fulltick") is a cross-platform C++ GUI toolkit for
+      `FLTK <http://www.fltk.org/>`_ (pronounced "fulltick") is a cross-platform C++ GUI toolkit for
       UNIX/Linux (X11), Microsoft Windows, and MacOS X
 
+  freetype
+      `freetype <http://www.freetype.org/>`_ is a font rasterization
+      library used by matplotlib which supports TrueType, Type 1, and
+      OpenType fonts.
+
+
   GDK
       The Gimp Drawing Kit for GTK+
 
   GTK
-      The GTK graphical user interface library
+      The GIMP Toolkit (`GTK <http://www.gtk.org/>`_) graphical user interface library
 
   JPG
-      A compression method and file format for photographic images
+      The Joint Photographic Experts Group (`JPEG
+      <http://en.wikipedia.org/wiki/Jpeg>`_) compression method and
+      file format for photographic images
+
+  numpy
+      `numpy <http://numpy.scipy.org>`_ is the standard numerical
+      array library for python, the successor to Numeric and numarray.
+      numpy provides fast operations for homogeneous data sets and
+      common mathematical operations like correlations, standard
+      deviation, fourier transforms, and convolutions.
 
   PDF
-      Adobe's Portable Document Format
+      Adobe's Portable Document Format (`PDF <http://en.wikipedia.org/wiki/Portable_Document_Format>`_)
 
   PNG
-      PNG stands for Portable Network Graphics, a raster graphics format that
-      employs lossless data compression which is more suitable for line art
-      than the lossy jpg format. Unlike the gif format, png is not encumbered
-      by requirements for a patent license.
+      Portable Network Graphics (`PNG
+      <http://en.wikipedia.org/wiki/Portable_Network_Graphics>`_), a raster graphics format
+      that employs lossless data compression which is more suitable
+      for line art than the lossy jpg format. Unlike the gif format,
+      png is not encumbered by requirements for a patent license.
 
   PS
-      Postscript
+      Postscript (`PS <http://en.wikipedia.org/wiki/PostScript>`_) is a
+      vector graphics ASCII text language widely used in printers and
+      publishing.  Postscript was developerd by adobe systems and is
+      starting to show its age: for example is does not have an alpha
+      channel.  PDF was designed in part as a next-generation document
+      format to replace postscript
+
+  pyfltk
+      `pyfltk <http://pyfltk.sourceforge.net/>`_ provides python
+      wrappers for the :term:`FLTK` widgets library for use with
+      FLTKAgg
+
+  pygtk
+      `pygtk <http://www.pygtk.org/>`_ provides python wrappers for
+      the :term:`GTK` widgets library for use with the GTK or GTKAgg
+      backend.  Widely used on linux, and is often packages as
+      'python-gtk2'
+
+  pyqt
+      `pyqt <http://wiki.python.org/moin/PyQt>`_ provides python
+      wrappers for the :term:`Qt` widgets library and is requied by
+      the matplotlib QtAgg and Qt4Agg backends.  Widely used on linux
+      and windows; many linux distributions package this as
+      'python-qt3' or 'python-qt4'.
+
+  python
+      `python <http://python.org>`_ is an object oriented interpreted
+      language widely used for scripting, application development, web
+      application servers, scientific computing and more.
 
   Qt
-      Qt is a cross-platform application framework for desktop and embedded
-      development.
+      `Qt <http://trolltech.com/products/qt/>`__ is a cross-platform
+      application framework for desktop and embedded development.
 
   Qt4
-      Qt4 is the most recent version of Qt cross-platform application framework
-      for desktop and embedded development.
+      `Qt4 <http://trolltech.com/products/qt/>`__ is the most recent
+      version of Qt cross-platform application framework for desktop
+      and embedded development.
 
   raster graphics
-      Raster graphics, or bitmaps, represent an image as an array of pixels
-      which is resolution dependent. Raster graphics are generally most
-      practical for photo-realistic images, but do not scale easily without
-      loss of quality.  See `raster graphics <http://en.wikipedia.org/wiki/Raster_graphics>`_
+      `Raster graphics
+      <http://en.wikipedia.org/wiki/Raster_graphics>`_, or bitmaps,
+      represent an image as an array of pixels which is resolution
+      dependent. Raster graphics are generally most practical for
+      photo-realistic images, but do not scale easily without loss of
+      quality.
 
   SVG
-      The Scalable Vector Graphics format.
+      The Scalable Vector Graphics format (`SVG
+      <http://en.wikipedia.org/wiki/Svg>`_).  An XML based vector
+      graphics format supported by many web browsers.
 
   TIFF
-      Tagged Image File Format
+      Tagged Image File Format (`TIFF
+      <http://en.wikipedia.org/wiki/Tagged_Image_File_Format>`_) is a
+      file format for storing images, including photographs and line
+      art.
 
   Tk
-      Tk is a graphical user interface for Tcl and many other dynamic
-      languages. It can produce rich, native applications that run unchanged
-      across Windows, Mac OS X, Linux and more.
+      `Tk <http://www.tcl.tk/>`_ is a graphical user interface for Tcl
+      and many other dynamic languages. It can produce rich, native
+      applications that run unchanged across Windows, Mac OS X, Linux
+      and more.
+
+  vector graphics
+      `vector graphics
+      <http://en.wikipedia.org/wiki/Vector_graphics>`_ use geometrical
+      primitives based upon mathematical equations to represent images
+      in computer graphics. Primitives can include points, lines,
+      curves, and shapes or polygons. Vector graphics are scalable,
+      which means that they can be resized without suffering from
+      issues related to inherent resolution like are seen in raster
+      graphics. Vector graphics are generally most practical for
+      typesetting and graphic design applications.
+
+  wxpython
+      `wxpython <http://www.wxpython.org/>`_ provides python wrappers
+      for the :term:`wxWidgets` library for use with the WX and WXAgg
+      backends.  Widely used on linux, OS-X and windows, it is often
+      packaged by linux distributions as 'python-wxgtk'
 
   wxWidgets
-      A cross-platform GUI and tools library for GTK, MS Windows, and MacOS.
+      `WX <http://www.wxwidgets.org/>`_ is cross-platform GUI and
+      tools library for GTK, MS Windows, and MacOS.  It uses native
+      widgets for each operating system, so applications will have the
+      look-and-feel that users on that operating system expect.
 
-  vector graphics
-      The use of geometrical primitives based upon mathematical equations to
-      represent images in computer graphics. Primitives can include points,
-      lines, curves, and shapes or polygons. Vector graphics are scalable,
-      which means that they can be resized without suffering from issues
-      related to inherent resolution like are seen in raster graphics. Vector
-      graphics are generally most practical for typesetting and graphic design
-      applications.  See `vector graphics <http://en.wikipedia.org/wiki/Vector_graphics>`_

doc/make.py

@@ -17,7 +17,11 @@ def check_build():
 def sf():
     'push a copy to the sf site'
     os.system('cd build; rsync -avz html jdh2358@matplotlib.sf.net:/home/groups/m/ma/matplotlib/htdocs/doc/ -essh')
-    os.system('cd build/latex; scp Matplotlib.pdf jdh2358@matplotlib.sf.net:/home/groups/m/ma/matplotlib/htdocs/doc/')
+
+def sfpdf():
+    'push a copy to the sf site'
+
+    #os.system('cd build/latex; scp Matplotlib.pdf jdh2358@matplotlib.sf.net:/home/groups/m/ma/matplotlib/htdocs/doc/')
 
 def figs():
     os.system('cd users/figures/ && python make.py')
@@ -73,6 +77,7 @@ def all():
          'latex':latex,
          'clean':clean,
          'sf':sf,
+         'sfpdf':sfpdf,
          'all':all,
          }
 

doc/pyplots/auto_subplots_adjust.py

@@ -0,0 +1,19 @@
+import matplotlib.pyplot as plt
+
+fig = plt.figure()
+ax = fig.add_subplot(111)
+ax.plot(range(10))
+ax.set_yticks((2,5,7))
+labels = ax.set_yticklabels(('really, really, really', 'long', 'labels'))
+
+def on_draw(event):
+   for label in labels:
+       bbox = label.get_window_extent()
+       if bbox.xmin<0:
+           fig.subplots_adjust(left=1.1*fig.subplotpars.left)
+           fig.canvas.draw()
+           break
+
+fig.canvas.mpl_connect('draw_event', on_draw)
+
+plt.show()

doc/users/installing.rst

@@ -14,18 +14,18 @@ installing matplotlib. Windows users only need the first two (python
 and numpy) since the others are built into the matplotlib windows
 installers available for download at the sourceforge site.
 
-python 2.4 (or later but not python3)
-    matplotlib requires python 2.4 or later
+:term:`python` 2.4 (or later but not python3)
+    matplotlib requires python 2.4 or later (`download <http://www.python.org/download/>`__)
 
-numpy 1.1 (or later)
-    array support for python
+:term:`numpy` 1.1 (or later)
+    array support for python (`download <http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`__)
 
 libpng 1.1 (or later)
-    library for loading and saving PNG files. libpng requires zlib. If
+    library for loading and saving :term:`PNG` files (`download <http://www.libpng.org/pub/png/libpng.html>`__). libpng requires zlib. If
     you are a windows user, you can ignore this since we build support
-    into the matplotlib single click installer.
+    into the matplotlib single click installer
 
-freetype 1.4 (or later)
+:term:`freetype` 1.4 (or later)
     library for reading true type font files. If you are a windows
     user, you can ignore this since we build support into the
     matplotlib single click installer.
@@ -37,25 +37,25 @@ matplotlib with a user interface toolkit. See
 :ref:`what-is-a-backend` for more details on the optional matplotlib
 backends and the capabilities they provide
 
-tk 8.3 or later
+:term:`tk` 8.3 or later
     The TCL/Tk widgets library used by the TkAgg backend
 
-pyqt 3.1 or later
+:term:`pyqt` 3.1 or later
     The Qt3 widgets library python wrappers for the QtAgg backend
 
-pyqt 4.0 or later
+:term:`pyqt` 4.0 or later
     The Qt4 widgets library python wrappersfor the Qt4Agg backend
 
-pygtk 2.2 or later
+:term:`pygtk` 2.2 or later
     The python wrappers for the GTK widgets library for use with the GTK or GTKAgg backend
 
-wxpython 2.6 or later
+:term:`wxpython` 2.6 or later
     The python wrappers for the wx widgets library for use with the WXAgg backend
 
-wxpython 2.8 or later
+:term:`wxpython` 2.8 or later
     The python wrappers for the wx widgets library for use with the WX backend
 
-pyfltk 1.0 or later
+:term:`pyfltk` 1.0 or later
     The python wrappers of the FLTK widgets library for use with FLTKAgg
 
 **Required libraries that ship with matplotlib**
@@ -65,7 +65,7 @@ subversion, you can ignore this section. This is useful for matplotlib
 developers and packagers who may want to disable the matplotlib
 version and ship a packaged version.
 
-agg2.4
+:term:`agg` 2.4
     The antigrain C++ rendering engine
 
 pytz 2007g or later