DOC improved our installation documentation

matplotlib · phobson · Mar 23, 2017 · Mar 8, 2017 · Mar 11, 2017 · Mar 11, 2017
commit b55412ef1297c9965e8e416af8375ad50d978e60
diff --git a/INSTALL b/INSTALL
@@ -7,58 +7,57 @@
 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, there are several
-convenient options.
+.. note::

-Installing pre-built packages
-=============================
+    If you wish to contribute to the project, it's recommended you
+    :ref:`install the latest development version<install_from_source>`.

-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://www.continuum.io/downloads/>`_ or `miniconda
-<http://conda.pydata.org/miniconda.html>`_) 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.

+.. contents.. 
+
+Installing an official release
+==============================
+
+Matplotlib and most of its dependencies all available as wheel packages for
+OSX, windows and many linux distributions::
+
+  pip install -U numpy scipy scikit-learn
+
+Third-party distributions of Matplotlib
+=======================================
+
+Scientific Python distributions: Conda, Canopy...
+--------------------------------------------------
+
+The first option is to use one of the pre-packaged Python distributions that
+already provide Matplotlib built-in.  Both `Anaconda
+<https://www.continuum.io/downloads/>`_ and `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.

 Linux : using your package manager
 ----------------------------------

-If you are on Linux, you might prefer to use your package manager.  matplotlib
+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_.
-See :ref:`install_osx_binaries`.
-
 .. _installing_windows:

 Windows
 -------

-If you don't already have Python installed, we recommend using
-one of the `scipy-stack compatible Python distributions
+We strongly recommend using `scipy-stack compatible Python distributions
 <http://www.scipy.org/install.html>`_ such as WinPython, Python(x,y),
-Enthought Canopy, or Continuum Anaconda, which have matplotlib and many
-of its dependencies, plus other useful packages, preinstalled.
+Enthought Canopy, or Continuum Anaconda, which have Matplotlib and many of its
+dependencies, plus other useful packages, preinstalled.

 For `standard Python <https://www.python.org/downloads/>`_ installations,
-install matplotlib using pip_::
+install Matplotlib using pip_::

    python -m pip install -U pip setuptools
    python -m pip install matplotlib
@@ -103,7 +102,7 @@ for the official binaries.  GTK3 is not supported on Windows.
 The Windows wheels (:file:`*.whl`) on the `PyPI download page
 <https://pypi.python.org/pypi/matplotlib/>`_ do not contain test data
 or example code.
-If you want to try the many demos that come in the matplotlib source
+If you want to try the many demos that come in the Matplotlib source
 distribution, download the :file:`*.tar.gz` file and look in the
 :file:`examples` subdirectory.
 To run the test suite:
@@ -123,12 +122,12 @@ To run the test suite:
 Installing from source
 ======================

-If you are interested in contributing to matplotlib development,
+If you are interested in contributing to Matplotlib development,
 running the latest source code, or just like to build everything
-yourself, it is not difficult to build matplotlib from source.  Grab
+yourself, it is not difficult to build Matplotlib from source.  Grab
 the latest *tar.gz* release file from `the PyPI files page
 <https://pypi.python.org/pypi/matplotlib/>`_, or if you want to
-develop matplotlib or just need the latest bugfixed version, grab the
+develop Matplotlib or just need the latest bugfixed version, grab the
 latest git version :ref:`install-from-git`.

 The standard environment variables `CC`, `CXX`, `PKG_CONFIG` are respected.
@@ -141,7 +140,7 @@ cross compiling.
  export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config

 Once you have satisfied the requirements detailed below (mainly
-python, numpy, libpng and freetype), you can build matplotlib.
+python, numpy, libpng and freetype), you can build Matplotlib.
 ::

  cd matplotlib
@@ -152,145 +151,66 @@ We provide a `setup.cfg
 <https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template>`_
 file that goes with :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
+some of the optional libraries that Matplotlib ships with are
 installed, and so on.  This file will be particularly useful to those
-packaging matplotlib.
+packaging Matplotlib.

 If you have installed prerequisites to nonstandard places and need to
-inform matplotlib where they are, edit ``setupext.py`` and add the base
+inform Matplotlib where they are, edit ``setupext.py`` and add the base
 dirs to the ``basedir`` dictionary entry for your ``sys.platform``.
 e.g., if the header to some required library is in
 ``/some/path/include/someheader.h``, put ``/some/path`` in the
 ``basedir`` list for your platform.

 .. _install_requirements:

-Build requirements
------------------
-
-These are external packages which you will need to install before
-installing matplotlib.  If you are building on OSX, see
-:ref:`build_osx`. If you are building on Windows, see
-:ref:`build_windows`. If you are installing dependencies with a
-package manager on Linux, you may need to install the development
-packages (look for a "-dev" postfix) in addition to the libraries
-themselves.
-
-
-Required Dependencies
-^^^^^^^^^^^^^^^^^^^^^
-
-:term:`python` 2.7, 3.4, 3.5 or 3.6
-    `Download python <https://www.python.org/downloads/>`_.
-
-:term:`numpy` |minimum_numpy_version| (or later)
-    array support for python (`download numpy <http://www.numpy.org>`_)
-
-`setuptools <https://setuptools.readthedocs.io/en/latest/>`__
-    Setuptools provides extensions for python package installation.
-
-:term:`dateutil` 1.1 or later
-    Provides extensions to python datetime handling.  If using pip,
-    easy_install or installing from source, the installer will attempt
-    to download and install `python_dateutil` from PyPI.
-
-`pyparsing <https://pyparsing.wikispaces.com/>`__
-    Required for matplotlib's mathtext math rendering support.  If
-    using pip, easy_install or installing from source, the installer
-    will attempt to download and install `pyparsing` from PyPI.
-
-`libpng 1.2 (or later) <http://www.libpng.org>`__
-    library for loading and saving :term:`PNG` files (`download
-    <http://www.libpng.org/pub/png/libpng.html>`__). libpng requires
-    zlib.
-
-`pytz <http://pytz.sourceforge.net/>`__
-    Used to manipulate time-zone aware datetimes.
-    https://pypi.python.org/pypi/pytz
-
-:term:`FreeType` 2.3 or later
-    Library for reading true type font files. If using pip, easy_install or
-    installing from source, the installer will attempt to locate FreeType in
-    expected locations. If it cannot, try installing `pkg-config
-    <http://matplotlib.org/users/installing.html#optional-dependencies>`__,
-    a tool used to find required non-python libraries.
-
-`cycler <http://matplotlib.org/cycler/>`__ 0.10.0 or later
-   Composable cycle class used for constructing style-cycles
-
-`six <https://pypi.python.org/pypi/six>`_
-  Required for compatibility between python 2 and python 3
-
-
-Dependencies for python 2
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-`backports.functools_lru_cache <https://pypi.python.org/pypi/backports.functools_lru_cache>`_
-    Required for compatibility if running on Python 2.7.
-
-`subprocess32 <https://pypi.python.org/pypi/subprocess32/>`_
-    Optional, unix only.  Backport of the subprocess standard library from 3.2+
-    for Python 2.7. It provides better error messages and timeout support.
-
-Optional GUI framework
-^^^^^^^^^^^^^^^^^^^^^^
-
-These are optional packages which you may want to install to use
-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.
-
-:term:`tk` 8.3 or later, not 8.6.0 or 8.6.1
-    The TCL/Tk widgets library used by the TkAgg backend.
-
-    Versions 8.6.0 and 8.6.1 are known to have issues that may result
-    in segfaults when closing multiple windows in the wrong order.
-
-:term:`pyqt` 4.4 or later
-    The Qt4 widgets library python wrappers for the Qt4Agg backend
-
-:term:`pygtk` 2.4 or later
-    The python wrappers for the GTK widgets library for use with the
-    GTK or GTKAgg backend
-
-:term:`wxpython` 2.8 or later
-    The python wrappers for the wx widgets library for use with the
-    WX or WXAgg backend
-
-Optional external programs
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-`ffmpeg <https://www.ffmpeg.org/>`__/`avconv <https://libav.org/avconv.html>`__ or `mencoder <http://www.mplayerhq.hu/design7/news.html>`__
-    Required for the animation module to be save out put to movie
-    formats.
-
-`ImageMagick <http://www.imagemagick.org/script/index.php>`__
-    Required for the animation module to be able to save to animated gif.
-
-Optional dependencies
-^^^^^^^^^^^^^^^^^^^^^
-
-`Pillow <http://python-pillow.org/>`__
-    If Pillow is installed, matplotlib can read and write a larger
-    selection of image file formats.
-
-`pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`__
-    A tool used to find required non-python libraries.  This is not strictly
-    required, but can make installation go more smoothly if the libraries and
-    headers are not in the expected locations.
-
-
-Required libraries that ship with matplotlib
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:term:`agg` 2.4
-    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.
-
-`qhull` 2012.1
-    A library for computing Delaunay triangulations.
-
-`ttconv`
-   truetype font utility
+Dependencies
+------------
+
+Matplotlib requires a large number of dependencies:
+
+  * `Python <https://www.python.org/downloads/>`_ (>= 2.7 or >= 3.4)
+  * `numpy <http://www.numpy.org>`_ (>= |minimum_numpy_version|)
+  * `setuptools <https://setuptools.readthedocs.io/en/latest/>`__
+  * `dateutil` (>= 1.1)
+  * `pyparsing <https://pyparsing.wikispaces.com/>`__
+  * `libpng <http://www.libpng.org>`__ ( >= 1.2) 
+  * `pytz <http://pytz.sourceforge.net/>`__
+  * FreeType` (>= 2.3)
+  * `cycler <http://matplotlib.org/cycler/>`__ (>= 0.10.0)
+  * `six <https://pypi.python.org/pypi/six>`_
+  * `backports.functools_lru_cache <https://pypi.python.org/pypi/backports.functools_lru_cache>`_
+    (for Python 2.7 only)
+  * `subprocess32 <https://pypi.python.org/pypi/subprocess32/>`_ (for Python
+    2.7 only)
+
+Optionally, you can also install a number of packages to enables better user
+interface toolkit. See :ref:`what-is-a-backend` for more details on the
+optional Matplotlib backends and the capabilities they provide.
+
+  * :term:`tk` (>= 8.3, != 8.6.0 or 8.6.1): for the TkAgg backend;
+  * :term:`pyqt` (>= 4.4): for the Qt4Agg backend;
+  * :term:`pygtk` (>= 2.4): for the GTK and the GTKAgg backend;
+  * :term:`wxpython` (>= 2.8 or later): for the WX or WXAgg backend.
+
+For better support of animation output format and image file format, you can
+install the following:
+
+  * `ffmpeg <https://www.ffmpeg.org/>`__/`avconv
+    <https://libav.org/avconv.html>`__ or `mencoder
+    <http://www.mplayerhq.hu/design7/news.html>`__ (for saving movies);
+  * `ImageMagick <http://www.imagemagick.org/script/index.php>`__ (for saving
+    animated gifs);
+  * `Pillow <http://python-pillow.org/>`__ (for a larger selection of image
+    file format).
+
+.. note::
+
+   Matplotlib depends on a large number of non-python libraries. 
+   `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`__
+   can be used to find required non-python libraries and thus make install go
+   more smoothly if the libraries and headers are not in the expected
+   locations.


 .. _build_linux:
@@ -301,17 +221,17 @@ Building on Linux
 It is easiest to use your system package manager to install the dependencies.

 If you are on Debian/Ubuntu, you can get all the dependencies
-required to build matplotlib with::
+required to build Matplotlib with::

   sudo apt-get build-dep python-matplotlib

 If you are on Fedora/RedHat, you can get all the dependencies required
-to build matplotlib by first installing ``yum-builddep`` and then
+to build Matplotlib by first installing ``yum-builddep`` and then
 running::

   su -c "yum-builddep python-matplotlib"

-This does not build matplotlib, but it does get and install the
+This does not build Matplotlib, but it does get and install the
 build dependencies, which will make building from source easier.


@@ -340,7 +260,7 @@ Example usage::

  port install libpng freetype pkgconfig

-To install matplotlib from source, execute:
+To install Matplotlib from source, execute:

 Example usage::

@@ -387,7 +307,7 @@ how to install and setup such environments. If in doubt: use python 3.5 as it mo
 without fiddling with environment variables::

  # create a new environment with the required packages
-  conda create  -n "matplotlib_build" python=3.4 numpy python-dateutil pyparsing pytz tornado "cycler>=0.10" tk libpng zlib freetype
+  conda create  -n "matplotlib_build" python=3.5 numpy python-dateutil pyparsing pytz tornado "cycler>=0.10" tk libpng zlib freetype
  activate matplotlib_build
  # if you want a qt backend, you also have to install pyqt (be aware that pyqt doesn't mix well if
  # you have created the environment with conda-forge already activated...)