DOC: comprehensive rewrite of OSX install docs

Katy's recent edits were a big improvement, but the faq install
instructions for OSX had also got horribly out of date.  The main thing
that has changed is that wheels are now the default binary installation
format, and, even if we are going to provide eggs, no-one should be
using easy_install now.

Author: matthew-brett

INSTALL

@@ -9,19 +9,36 @@ Installing
 There are many 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 Continuum.io
-Python distribution `(Anaconda)
-<https://store.continuum.io/cshop/anaconda/>`_ and the Enthought
-distribution `(Canopy) <https://www.enthought.com/products/canopy/>`_
-are both excellent choices that "just work" out of the box for any
-platform.  Both of these packages include matplotlib and
-*lots* of other useful tools.
-Another excellent alternative for Windows users is `Python (x, y)
-<https://code.google.com/p/pythonxy>`_ . matplotlib is also packaged for almost
-every major Linux distribution. So if you are on Linux, your package
-manager will probably provide matplotlib prebuilt.
+the details (and potential complications) on this page, there are several
+convenient options.
+
+Most platforms : scientific Python distributions
+================================================
+
+The first option is to use one of the pre-packaged python distributions that
+already provide matplotlib built-in.  The Continuum.io Python distribution
+`(Anaconda) <https://store.continuum.io/cshop/anaconda/>`_ and the Enthought
+distribution `(Canopy) <https://www.enthought.com/products/canopy/>`_ are both
+excellent choices that "just work" out of the box for Windows, OSX and common
+Linux platforms.  Both of these distributions include matplotlib and *lots* of
+other useful tools.  Another excellent alternative for Windows users is
+`Python (x, y) <https://code.google.com/p/pythonxy>`_ .
+
+Linux : using your package manager
+==================================
+
+If you are on Linux, you might prefer to use your package manager.  matplotlib
+is packaged for almost every major Linux distribution.
+
+* Debian / Ubuntu : ``sudo apt-get install python-matplotlib``
+* Fedora / Redhat : ``sudo yum install python-matplotlib``
+
+Mac OSX - using pip
+===================
+
+If you are on Mac OSX you can probably install matplotlib binaries using the
+standard Python installation program `pip <https://pypi.python.org/pip>`_.
+See :ref:`installing-osx-binaries`.
 
 Manually installing pre-built packages
 ======================================
@@ -36,7 +53,7 @@ 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
+Once you have Python up and running, you will need to install `numpy
 <http://www.numpy.org/>`_.  numpy provides high-performance array data
 structures and mathematical functions, and is a requirement for
 matplotlib.  You can test your progress::
@@ -87,7 +104,6 @@ python console, there are some issues relating to user interface
 toolkits and interactive settings that are discussed in
 :ref:`mpl-shell`.
 
-
 Installing on Windows
 ---------------------
 
@@ -207,7 +223,7 @@ manager on Linux, you may need to install the development packages
 
 .. note::
 
-    If you are on debian/ubuntu, you can get all the dependencies
+    If you are on Debian/Ubuntu, you can get all the dependencies
     required to build matplotlib with::
 
       sudo apt-get build-dep python-matplotlib

doc/faq/installing_faq.rst

@@ -4,11 +4,9 @@
  Installation
 *************
 
-
 .. contents::
    :backlinks: none
 
-
 Report a compilation problem
 ============================
 
@@ -181,12 +179,14 @@ OS-X Notes
 Which python for OS X?
 ----------------------
 
-Apple ships OS X with its own python, but it is generally recommended
-that users install an independent python system and use that
-as the basis for installing libraries such as numpy and
-matplotlib.  By far the easiest method is to use one
-of the excellent python software collections that are now
-available:
+Apple ships OS X with its own Python, in ``/usr/bin/python``, and its own copy
+of matplotlib. Unfortunately, the way Apple currently installs its own copies
+of numpy, scipy and matplotlib means that these packages are difficult to
+upgrade.  For that reason we strongly suggest that you install a fresh version
+of Python and use that as the basis for installing libraries such as numpy and
+matplotlib.  Once convenient way to install matplotlib with other useful
+Python software is to use one of the excellent Python scientific software
+collections that are now available:
 
 - Anaconda_ from `Continuum Analytics`_
 - Canopy_ from Enthought_
@@ -196,94 +196,173 @@ available:
 .. _Enthought: http://enthought.com
 .. _Continuum Analytics: http://continuum.io
 
-These collections include python itself and a wide range of
-libraries; if you need a library that is not available from
-the collection, you can install it yourself using standard
-methods such as *pip*.
+These collections include Python itself and a wide range of libraries; if you
+need a library that is not available from the collection, you can install it
+yourself using standard methods such as *pip*.  Continuum and Enthought offer
+their own installation support for these collections; see the Ananconda and
+Canopy web pages for more information.
+
+Other options for a fresh Python install are the standard installer from
+`python.org <https://www.python.org/downloads/mac-osx/>`_, or installing
+Python using a general OSX package management system such as `homebrew
+<http://brew.sh>`_ or `macports <http://www.macports.org>`_.  Power users on
+OSX will likely want one of homebrew or macports on their system to install
+open source software packages, but it is perfectly possible to use these
+systems with another source for your Python binary, such as Anaconda, Canopy
+or Python.org Python.
 
-If you choose not to use a collection, then you may use an
-installer from `python.org
-<https://www.python.org/downloads/mac-osx/>`_, or use a
-general package management system such as `homebrew
-<http://brew.sh>`_ or `macports <http://www.macports.org>`_.
-Whatever you choose, choose one and stick with it--don't try
-to mix homebrew and macports, for example.  You may,
-however, use homebrew or macports for all your non-python
-software, and still use Anaconda_ or Canopy_ for your python
-system.
+.. _install_osx_binaries:
 
+Installing OSX binary wheels
+----------------------------
 
+If you are using recent Python from http://www.python.org, Macports or
+Homebrew, then you can use the standard pip installer to install matplotlib
+binaries in the form of wheels.
 
-.. _install_osx_binaries:
+Python.org Python
+^^^^^^^^^^^^^^^^^
 
-Installing OSX binaries
------------------------
+* Install pip following instructions here: http://pip.readthedocs.org
+
+Then::
+
+    pip install matplotlib
+
+Macports
+^^^^^^^^
+
+For Python 2.7::
+
+    sudo port install py27-pip
+    sudo pip-2.7 install matplotlib
+
+For Python 3.4::
+
+    sudo port install py34-pip
+    sudo pip-3.4 install matplotlib
+
+Homebrew
+^^^^^^^^
+
+For Python 2.7::
+
+    pip2 install matplotlib
+
+For Python 3.4::
 
-If you want to install matplotlib from one of the binary installers we
-build, you have two choices: a mpkg installer, which is a typical
-Installer.app, or a binary OSX egg, which you can install via
-setuptools' easy_install.
+    pip3 install matplotlib
+
+You might also want to install IPython; we recommend you install IPython with
+the IPython notebook option, like this:
+
+* Python.org Python:  ``pip install ipython[notebook]``
+* Macports ``sudo pip-2.7 install ipython[notebook]`` or ``sudo pip-3.4
+  install ipython[notebook]``
+* Homebrew ``pip2 install ipython[notebook]`` or ``pip3 install
+  ipython[notebook]``
+
+Installing via OSX mpkg installer package
+-----------------------------------------
+
+matplotlib also has a disk image (``.dmg``) installer, which contains a
+typical Installer.app package to install matplotlib.  You should use binary
+wheels instead of the disk image installer if you can, because:
+
+* wheels work with Python.org Python, homebrew and macports, the disk image
+  installer only works with Python.org Python.
+* The disk image installer doesn't check for recent versions of packages that
+  matplotlib depends on, and unconditionally installs the versions of
+  dependencies contained in the disk image installer.  This can overwrite
+  packages that you have already installed, which might cause problems for
+  other packages, if you have a pre-existing Python.org setup on your
+  computer.
+
+If you still want to use the disk image installer, read on.
 
 .. note::
-   Before installing any of the binary packages, be sure that all of the
-   packages were compiled for the same version of python.
-   Often, the download site for NumPy and matplotlib will display a
-   supposed 'current' version of the package, but you may need to choose
-   a different package from the full list that was built for your
-   combination of python and OSX.
-
-The mkpg installer will have a "zip" extension, and will have a name
-like :file:`matplotlib-1.2.0-py2.7-macosx10.5_mpkg.zip`.
+   Before installing via the disk image installer, be sure that all of the
+   packages were compiled for the same version of python.  Often, the download
+   site for NumPy and matplotlib will display a supposed 'current' version of
+   the package, but you may need to choose a different package from the full
+   list that was built for your combination of python and OSX.
+
+The disk image installer will have a ``.dmg`` extension, and will have a name
+like :file:`matplotlib-1.4.0-py2.7-macosx10.5.dmg`.
 The name of the installer depends on which versions of python, matplotlib,
-and OSX it was built for.  You need to unzip this file using either the
-"unzip" command, or simply double clicking on the it. Then when you
-double-click on the resulting mpkd, which will have a name like
-:file:`matplotlib-1.2.0-py2.7-macosx10.5.mpkg`, it will run the
-Installer.app, prompt you for a password if you need system-wide
+and OSX it was built for.  You need to download this disk image ``.dmg``
+file. Next open the disk image file by double clicking, and find the new
+matplotlib disk image icon on your desktop.  Double click on that icon to show
+the contents of the image.  Then double-click on the ``.mpkg`` icon, which
+will have a name like :file:`matplotlib-1.4.0-py2.7-macosx10.5.mpkg`, it will
+run the Installer.app, prompt you for a password if you need system-wide
 installation privileges, and install to a directory like
-:file:`/Library/Python/2.7/site-packages/` (exact path depends on your
-python version).  This directory may not be in your python 'path' variable,
-so you should test your installation with::
+:file:`/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages`
+(exact path depends on your Python version).
+
+Checking your installation
+--------------------------
+
+The new version of matplotlib should now be on your Python "path".  Check this
+with one of these commands at the Terminal.app command line::
 
-  > python -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__'
+  python2.7 -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__'
 
-If you get an error like::
+(Python 2.7) or::
+
+  python3.4 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)'
+
+(Python 3.4).  You should see something like this::
+
+  1.4.0 /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib/__init__.pyc
+
+where ``1.4.0`` is the matplotlib version you just installed, and the path
+following depends on whether you are using Python.org Python, Homebrew or
+Macports.  If you see another version, or you get an error like this::
 
     Traceback (most recent call last):
       File "<string>", line 1, in <module>
     ImportError: No module named matplotlib
 
-then you will need to set your PYTHONPATH, eg::
+then check that the Python binary is the one you expected by doing one of
+these commands in Terminal.app::
 
-    export PYTHONPATH=/Library/Python/2.7/site-packages:$PYTHONPATH
+  which python2.7
 
-See also ref:`environment-variables`.
+or::
+
+  which python3.4
 
+If you get the result ``/usr/bin/python2.7``, then you are getting the Python
+installed with OSX, which is probably not what you want.  Try closing and
+restarting Terminal.app before running the check again. If that doesn't fix
+the problem, depending on which Python you wanted to use, consider
+reinstalling Python.org Python, or check your homebrew or macports setup.
+Remember that the disk image installer only works for Python.org Python, and
+will not get picked up by other Pythons.  If all these fail, please contact
+the mailing list.
 
 Windows Notes
 =============
 
-Recommendation: use one of the excellent multi-platform
-python collections which include python itself and a wide
-range of libraries including matplotlib:
+We recommend you use one of the excellent python collections which include
+Python itself and a wide range of libraries including matplotlib:
 
 - Anaconda_ from `Continuum Analytics`_
 - Canopy_ from Enthought_
+- `Python (x, y) <https://code.google.com/p/pythonxy>`_
 
-A Windows-only alternative is:
-
-- `python (x, y) <http://www.pythonxy.com>`_
+Python (X, Y) is Windows-only, whereas Anaconda and Canopy are cross-platform.
 
 .. _windows-installers:
 
-Binary installers for Windows
------------------------------
+Standalone binary installers for Windows
+----------------------------------------
 
-If you have already installed python, you can use one of the
+If you have already installed Python and numpy, you can use one of the
 matplotlib binary installers for windows -- you can get these from the
-`download <http://matplotlib.org/downloads.html>`_ site.
-Choose the files that match your version of python (eg ``py2.7`` if
-you installed Python 2.7) which have the ``exe`` extension.  If you
-haven't already installed python, you can get the official version
-from the `python web site <http://python.org/download/>`_.
-
+`download <http://matplotlib.org/downloads.html>`_ site.  You will first need
+to install Choose the files that match your version of python (eg ``py2.7`` if
+you installed Python 2.7) which have the ``exe`` extension.  If you haven't
+already installed python, you can get the official version from the `python
+web site <http://python.org/download/>`_.