Revision: 6213
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6213&view=rev
Author: jdh2358
Date: 2008-10-15 18:48:00 +0000 (Wed, 15 Oct 2008)
Log Message:
-----------
updates to installing and interactive shell docs
Modified Paths:
--------------
trunk/matplotlib/doc/_templates/index.html
trunk/matplotlib/doc/_templates/indexsidebar.html
trunk/matplotlib/doc/faq/installing_faq.rst
trunk/matplotlib/doc/users/index.rst
trunk/matplotlib/doc/users/installing.rst
Added Paths:
-----------
trunk/matplotlib/doc/users/shell.rst
Modified: trunk/matplotlib/doc/_templates/index.html
===================================================================
--- trunk/matplotlib/doc/_templates/index.html 2008-10-15 18:35:57 UTC (rev
6212)
+++ trunk/matplotlib/doc/_templates/index.html 2008-10-15 18:48:00 UTC (rev
6213)
@@ -22,10 +22,13 @@
matplotlib tries to make easy things easy and hard things possible.
You can generate plots, histograms, power spectra, bar charts,
errorcharts, scatterplots, etc, with just a few lines of code. For
- example, to make a histogram of data in x, you simply need to type
+ example, to generate 10,000 gaussian random numbers and make a
+ histogram plot binning the data into 100 bins, you simply need to type
<pre>
- >>> hist(x, 100) # use 100 bins
+ >>> from pylab import randn, hist
+ >>> x = randn(10000)
+ >>> hist(x, 100)
</pre>
For the power user, you have full control of line styles, font
Modified: trunk/matplotlib/doc/_templates/indexsidebar.html
===================================================================
--- trunk/matplotlib/doc/_templates/indexsidebar.html 2008-10-15 18:35:57 UTC
(rev 6212)
+++ trunk/matplotlib/doc/_templates/indexsidebar.html 2008-10-15 18:48:00 UTC
(rev 6213)
@@ -1,12 +1,16 @@
<h3>Download</h3>
<p>Current version: <b>{{ version }}</b></p>
-<p>Download matplotlib from the sourceforge <a
-href="http://sourceforge.net/projects/matplotlib";>project</a> page.
+<p>Download matplotlib from the sourceforge <a
+href="http://sourceforge.net/projects/matplotlib";>project</a> page
+(but first take a look at the <a
+href="{{ pathto('users/installing') }}">installing</a> page).
-There are also optional <a href="{{ pathto('users/toolkits') }}">toolkits</a>
for matplotlib.
+<p>
+There are also optional <a href="{{ pathto('users/toolkits') }}">toolkits</a>
for matplotlib.
+</p>
<h3>Need help?</h3>
-<p>Check the <a href="{{ pathto('contents') }}">docs</a>, the <a
+<p>Check the <a href="{{ pathto('contents') }}"}>docs</a>, the <a
href="{{ pathto('faq/index') }}">faq</a>, and join the matplotlib mailing <a
href="http://sourceforge.net/project/showfiles.php?group_id=80706";>lists</a>
@@ -20,5 +24,5 @@
<a href="{{ pathto('users/screenshots') }}">screenshots</a> and <a
href=examples>examples</a>
+
-
Modified: trunk/matplotlib/doc/faq/installing_faq.rst
===================================================================
--- trunk/matplotlib/doc/faq/installing_faq.rst 2008-10-15 18:35:57 UTC (rev
6212)
+++ trunk/matplotlib/doc/faq/installing_faq.rst 2008-10-15 18:48:00 UTC (rev
6213)
@@ -90,10 +90,10 @@
<locating-matplotlib-install>`
-.. _install_svn:
+.. _install-svn:
-How to install from svn
-=======================
+How to install from svn?
+========================
Checking out the main source::
@@ -249,6 +249,21 @@
OS-X questions
==============
+.. _which-python-for-osx:
+
+Which python for OS X?
+----------------------
+
+Apple ships with its own python, many users have had trouble
+with it so there are alternatives. If it is feasible for you, we
+recommend the enthought python distribution `EPD
+<http://www.enthought.com/products/epd.php>`_ for OS X (which comes
+with matplotlib and much more) or the
+`MacPython <http://wiki.python.org/moin/MacPython/Leopard>`_ or the
+official OS X version from `python.org
+<http://www.python.org/download/>`_.
+
+
.. _easy-install-osx-egg:
How can I easy_install my egg?
Modified: trunk/matplotlib/doc/users/index.rst
===================================================================
--- trunk/matplotlib/doc/users/index.rst 2008-10-15 18:35:57 UTC (rev
6212)
+++ trunk/matplotlib/doc/users/index.rst 2008-10-15 18:48:00 UTC (rev
6213)
@@ -17,6 +17,7 @@
pyplot_tutorial.rst
navigation_toolbar.rst
customizing.rst
+ shell.rst
index_text.rst
artists.rst
event_handling.rst
Modified: trunk/matplotlib/doc/users/installing.rst
===================================================================
--- trunk/matplotlib/doc/users/installing.rst 2008-10-15 18:35:57 UTC (rev
6212)
+++ trunk/matplotlib/doc/users/installing.rst 2008-10-15 18:48:00 UTC (rev
6213)
@@ -4,11 +4,113 @@
Installing
**********
-Dependencies
-============
+There are lots of different ways to install matplotlib, and the best
+way depends on what operating system you are using, what you already
+have installed, and how you want to use it. To avoid wading through
+all the details (and potential complications) on this page, the
+easiest thing for you to do is use one of the pre-packaged python
+distributions that already provide matplotlib built in. The Enthought
+Python Distribution `(EPD)
+<http://www.enthought.com/products/epd.php>`_ for Windows, OS X or
+Redhat is an excellent choice that "just works" out of the box.
+Another excellent alternative for Windows users is `Python (x, y)
+<http://www.pythonxy.com/foreword.php>`_ which tends to be updated a
+bit more frequently. Both of these packages include matplotlib and
+pylab, and *lots* of other useful tools. matplotlib is also packaged
+for pretty much every major linux distribution, so if you are on linux
+your package manager will probably provide matplotlib prebuilt.
-**Requirements**
+One single click installer and you are done.
+Ok, so you want to do it the hard way?
+======================================
+
+For some people, the prepackaged pythons discussed above are not an
+option. That's OK, it's usually pretty easy to get a custom install
+working. You will first need to find out if you have python installed
+on your machine, and if not, install it. The official python builds
+are available for download `here <http://www.python.org/download>`_,
+but OS X users please read :ref:`which-python-for-osx`.
+
+Once you have python up and running, you will need to install `numpy
+<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_.
+numpy provides high performance array data structures and mathematical
+functions, and is a requirement for matplotlib. You can test your
+progress::
+
+ >>> import numpy
+ >>> print numpy.__versions__
+
+matplotlib requires numpy version 1.1 or later. Although it is not a
+requirement to use matplotlib, we strongly encourage you to install
+`ipython <http://ipython.scipy.org/dist>`_, which is an interactive
+shell for python that is matplotlib aware. Once you have ipython,
+numpy and matplotlib installed, ipython's "pylab" mode you have a
+matlab-like environment that automatically handles most of the
+configuration details for you, so you can get up and running quickly::
+
+ [EMAIL PROTECTED]:~> ipython -pylab
+ Python 2.4.5 (#4, Apr 12 2008, 09:09:16)
+ IPython 0.9.0 -- An enhanced Interactive Python.
+
+ Welcome to pylab, a matplotlib-based Python environment.
+ For more information, type 'help(pylab)'.
+
+ In [1]: x = randn(10000)
+
+ In [2]: hist(x, 100)
+
+And a *voila*, a figure pops up. But we are putting the cart ahead of
+the horse -- first we need to get matplotlib installed. We provide
+prebuilt binaries for OS X and Windows on the matplotlib `download
+<http://sourceforge.net/project/showfiles.php?group_id=80706>`_ page.
+Click on the latest release of the "matplotlib" package, choose your
+python version (2.4 or 2.5) and your platform (macosx or win32) and
+you should be good to go. If you have any problems, please check the
+:ref:`installing-faq`, google around a little bit, and post a question
+the `mailing list
+<http://sourceforge.net/project/showfiles.php?group_id=80706>`_.
+
+Note that when testing matplotlib installations from the interactive
+python console, there are some issues relating to user interface
+toolkits and interactive settings that are discussed in
+:ref:`mpl-shell`.
+
+.. _install_from_source:
+
+Installing from source
+======================
+
+If you are interested perhaps in contributing to matplotlib
+development, or just like to build everything yourself, it is not
+difficult to build matplotlib from source. Grab the lattest *tar.gz*
+release file from `sourceforge
+<http://sourceforge.net/project/showfiles.php?group_id=80706>`_, or if
+you want to develop matplotlib or just need the latest bugfixed
+version, grab the latest svn version :ref:`install-svn`.
+
+Once you have satisfied the requirements detailed below (mainly
+python, numpy, libpng and freetype), you build matplotlib in the usual
+way::
+
+ cd matplotlib
+ python setup.py build
+ python setup.py install
+
+We provide a `setup.cfg
+<http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/setup.cfg.template?view=markup>`
+file that lives along :file:`setup.py` which you can use to customize
+the build process, for example, which default backend to use, whether
+some of the optional libraries that matplotlib ships with are
+installed, and so on. This file will be particularly useful to those
+packaging matplotlib.
+
+
+.. _install_requrements:
+
+Build requirements
+==================
+
These are external packages which you will need to install before
installing matplotlib. Windows users only need the first two (python
and numpy) since the others are built into the matplotlib windows
@@ -18,12 +120,14 @@
matplotlib requires python 2.4 or later (`download
<http://www.python.org/download/>`__)
:term:`numpy` 1.1 (or later)
- array support for python (`download
<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`__)
+ 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 :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
+ 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
:term:`freetype` 1.4 (or later)
library for reading true type font files. If you are a windows
@@ -60,32 +164,22 @@
**Required libraries that ship with matplotlib**
-If you are downloading matplotlib or installing from source or
-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.
-
:term:`agg` 2.4
- The antigrain C++ rendering engine
+ The antigrain C++ rendering engine. matplotlib links against the
+ agg template source statically, so it will not affect anything on
+ your system outside of matplotlib.
pytz 2007g or later
- timezone handling for python datetime objects
+ timezone handling for python datetime objects. By default,
+ matplotlib will install pytz if it isn't already installed on your
+ system. To override the default, use setup.cfg to force or
+ prevent installation of pytz.
dateutil 1.1 or later
- extensions to python datetime handling
+ extensions to python datetime handling. By
+ default, matplotlib will install dateutil if it isn't already
+ installed on your system. To override the default, use setup.cfg
+ to force or prevent installation of dateutil.
-**Optional libraries that ship with matplotlib**
-As above, if you are downloading matplotlib or installing from source
-or 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.
-enthought traits 2.6
- The traits component of the Enthought Tool Suite used in the
- experimental matplotlib traits rc system. matplotlib has decided
- to stop installing this library so packagers should not distribute
- the version included with matplotlib. packagers do not need to
- list this as a requirement because the traits support is
- experimental and disabled by default.
-
Added: trunk/matplotlib/doc/users/shell.rst
===================================================================
--- trunk/matplotlib/doc/users/shell.rst (rev 0)
+++ trunk/matplotlib/doc/users/shell.rst 2008-10-15 18:48:00 UTC (rev
6213)
@@ -0,0 +1,142 @@
+.. _mpl-shell:
+
+**********************************
+Using matplotlib in a python shell
+**********************************
+
+By default, matplotlib defers drawing until the end of the script
+because drawing can be an expensive opertation, and you may not want
+to update the plot every time a single property is changed, only once
+after all the properties have changed.
+
+But when working from the python shell, you usually do want to update
+the plot with every command, eg, after changing the
+:func:`~matplotlib.pyplot.xlabel`, or the marker style of a line.
+While this is simple in concept, in practice it can be tricky, because
+matplotlib is a graphical user interface application under the hood,
+and there are some tricks to make the applications work right in a
+python shell.
+
+
+.. _ipython-pylab:
+
+Ipython to the rescue
+=====================
+
+Fortunately, `ipython <http://ipython.scipy.org/dist>`_, an enhanced
+interactive python shell, has figured out all of these tricks, and is
+matplotlib aware, so when you start ipython in the *pylab* mode::
+
+
+ [EMAIL PROTECTED]:~> ipython -pylab
+ Python 2.4.5 (#4, Apr 12 2008, 09:09:16)
+ IPython 0.9.0 -- An enhanced Interactive Python.
+
+ Welcome to pylab, a matplotlib-based Python environment.
+ For more information, type 'help(pylab)'.
+
+ In [1]: x = randn(10000)
+
+ In [2]: hist(x, 100)
+
+it sets everything up for you so interactive plotting works as you
+would expect it to. Call :func:`~matplotlib.pyplot.figure` and a
+figure window pops up, call :func:`~matplotlib.pyplot.plot` and your
+data appears in the figure window.
+
+Note in the example above that we did not import any matplotlib names
+because in pylab mode, ipython will import them automatically.
+ipython also turns on *interactive* mode for you, which causes every
+pyplot command to trigger a figure update, and also provides a
+matplotlib aware ``run`` command to run matplotlib scripts
+efficiently. ipython will turn off interactive mode during a ``run``
+command, and then restore the interactive state at the end of the
+run so you can continue tweaking the figure manually.
+
+There has been a lot of recent work to embed ipython, with pylab
+support, into various GUI applications, so check on the ipython
+mailing `list
+<http://projects.scipy.org/mailman/listinfo/ipython-user>`_ for the
+latest status.
+
+.. _other-shells:
+
+Other python interpreters
+=========================
+
+If you can't use ipython, and still want to use matplotlib/pylab from
+an interactive python shell, eg the plain-ol standard python
+interactive interpreter, or the interpreter in your favorite IDE, you
+are going to need to understand what a matplotlib backend is
+:ref:`what-is-a-backend`.
+
+
+
+With the TkAgg backend, that uses the Tkinter user interface toolkit,
+you can use matplotlib from an arbitrary python shell. Just set your
+``backend : TkAgg`` and ``interactive : True`` in your
+:file:matplotlibrc file (see :ref:`customizing-matplotlib`) and fire
+up python. Then::
+
+ >>> from pylab import *
+ >>> plot([1,2,3])
+ >>> xlabel('hi mom')
+
+should work out of the box. Note, in batch mode, ie when making
+figures from scripts, interactive mode can be slow since it redraws
+the figure with each command. So you may want to think carefully
+before making this the default behavior.
+
+For other user interface toolkits and their corresponding matplotlib
+backends, the situation is complicated by the GUI mainloop which takes
+over the entire process. The solution is to run the GUI in a separate
+thread, and this is the tricky part that ipython solves for all the
+major toolkits that matplotlib supports. There are reports that
+upcoming versions of pygtk will place nicely with the standard python
+shell, so stay tuned.
+
+.. _controlling-interactive:
+
+Controlling interactive updating
+================================
+
+The *interactive* property of the pyplot interface controls whether a
+figure canvas is drawn on every pyplot command. If *interactive* is
+*False*, then the figure state is updated on every plot commands, but
+will only be drawn on explicit calls to
+:func:`~matplotlib.pyplot.draw`. When *interactive* is
+*True*, then every pyplot command triggers a draw.
+
+
+The pyplot interface provides 4 commands that are useful for
+interactive control.
+
+:func:`~matplotlib.pyplot.isinteractive`
+ returns the interactive setting *True|False*
+
+:func:`~matplotlib.pyplot.ion`
+ turns interactive mode on
+
+:func:`~matplotlib.pyplot.ioff`
+ turns interactive mode off
+
+:func:`~matplotlib.pyplot.draw`
+ forces a figure redraw
+
+When working with a big figure in which drawing is expensive, you may
+want to turn matplotlib's interactive setting off temporarily to avoid
+the performance hit::
+
+
+ >>> #create big-expensive-figure
+ >>> ioff() # turn updates off
+ >>> title('now how much would you pay?')
+ >>> xticklabels(fontsize=20, color='green')
+ >>> draw() # force a draw
+ >>> savefig('alldone', dpi=300)
+ >>> close()
+ >>> ion() # turn updating back on
+ >>> plot(rand(20), mfc='g', mec='r', ms=40, mew=4, ls='--', lw=3)
+
+
+
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Matplotlib-checkins mailing list
Matplotlib-checkins@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
