Merge pull request #3399 from jenshnielsen/cherrypick-v140

tacaswell · tacaswell · commit d68aa4e6ede4 · 2014-08-22T17:01:12.000-04:00
Cherrypick doc changes to v1.4.x
diff --git a/INSTALL b/INSTALL
@@ -12,100 +12,44 @@ 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.
 
+Installing pre-built packages
+=============================
+
 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/>`_ 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.  Another
+excellent alternative for Windows users is `Python (x, y)
+<https://code.google.com/p/pythonxy>`_ .
 
-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
-===================
+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
-======================================
-
-General instructions
---------------------
-
-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://www.numpy.org/>`_.  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.__version__
-
-matplotlib requires numpy version |minimum_numpy_version| or later.
-Although it is not a requirement to use matplotlib, we strongly
-encourage you to install `ipython <http://ipython.org>`_, which is an
-interactive shell for python that is matplotlib-aware.
-
-Next, we need to get matplotlib installed.  We provide prebuilt
-binaries for OS X and Windows on the matplotlib `download
-<http://matplotlib.org/downloads.html>`_.  Click on
-the latest release of the "matplotlib" package, choose your python
-version (2.6, 2.7, 3.3, or 3.4) and your platform (macosx or win32).  If you
-have any problems, please check the :ref:`installing-faq`, search
-using Google, and/or post a question the `mailing list
-<http://sourceforge.net/project/showfiles.php?group_id=80706>`_.
-
-If you are on Debian/Ubuntu linux, it suffices to do::
+See :ref:`install_osx_binaries`.
 
-  > sudo apt-get install python-matplotlib
 
-Instructions for installing our OSX binaries are found in the FAQ
-:ref:`install_osx_binaries`.
-
-
-Once you have ipython, numpy and matplotlib installed, you can use
-ipython's "pylab" mode to have a MATLAB-like environment that automatically
-handles most of the configuration details for you, so you can get up
-and running quickly::
-
-    johnh@flag:~> 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)
-
-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`.
-
-Installing on Windows
----------------------
+Windows
+-------
 
 If you don't already have Python installed, we recommend using
 one of the `scipy-stack compatible Python distributions
@@ -175,6 +119,8 @@ sys.prefix\Lib\site-packages\mpl_toolkits respectively, and install
 Pillow, MiKTeX, GhostScript, ffmpeg, avconv, mencoder, ImageMagick, and
 `Inkscape <http://inkscape.org/>`_.
 
+
+
 .. _install_from_source:
 
 Installing from source
@@ -213,31 +159,19 @@ e.g., if the header to some required library is in
 .. _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 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.
 
-.. note::
-
-    If you are on Debian/Ubuntu, you can get all the dependencies
-    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 running::
-
-       su -c "yum-builddep python-matplotlib"
 
-    This does not build matplotlib, but it does get the install the
-    build dependencies, which will make building from source easier.
+Required Dependencies
+^^^^^^^^^^^^^^^^^^^^^
 
-:term:`python` 2.6, 2.7, 3.1 or 3.2
+:term:`python` 2.6, 2.7, 3.3 or 3.4
     `Download python <http://www.python.org/download/>`_.
 
 :term:`numpy` |minimum_numpy_version| (or later)
@@ -267,7 +201,8 @@ libpng 1.2 (or later)
     build support into the matplotlib single-click installer
 
 
-**Optional GUI frameworks**
+Optional GUI framework
+^^^^^^^^^^^^^^^^^^^^^^
 
 These are optional packages which you may want to install to use
 matplotlib with a user interface toolkit. See
@@ -288,29 +223,29 @@ backends and the capabilities they provide.
     The python wrappers for the wx widgets library for use with the
     WX or WXAgg backend
 
-**Optional external programs**
-
+Optional external programs
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 ffmpeg/avconv or mencoder
     Required for the animation module to be save out put to movie
     formats.
 
 ImageMagick
     Required for the animation module to be able to save to animated gif.
 
-**Optional dependencies**
+Optional dependencies
+^^^^^^^^^^^^^^^^^^^^^
 
 `Pillow http://python-imaging.github.io/`__
     If Pillow is installed, matplotlib can read and write a larger
     selection of image file formats.
 
 
 :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.
+    library for reading true type font files.
 
-**Required libraries that ship with matplotlib**
 
+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
@@ -326,14 +261,46 @@ ImageMagick
 `ttconv`
    truetype font utility
 
+.. _build_linux:
+
+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::
+
+   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
+running::
+
+   su -c "yum-builddep python-matplotlib"
+
+This does not build matplotlib, but it does get the install the
+build dependencies, which will make building from source easier.
+
+
 .. _build_osx:
 
 Building on OSX
-===============
+---------------
 
 The build situation on OSX is complicated by the various places one
 can get the libpng and freetype requirements (darwinports, fink,
 /usr/X11R6) and the different architectures (e.g., x86, ppc, universal) and
 the different OSX version (e.g., 10.4 and 10.5). We recommend that you build
 the way we do for the OSX release: get the source from the tarball or the
 git repository and follow the instruction in :file:`README.osx`.
+
+.. _build_osx:
+
+Building on Windows
+-------------------
+
+Building for source on windows can be difficult.  Please see
+`matplotlib-windbuild
+<https://github.com/jbmohler/matplotlib-winbuild>`_ for detailed
+instructions, dependency source blobs, and helper scripts.
diff --git a/doc/faq/usage_faq.rst b/doc/faq/usage_faq.rst
@@ -114,6 +114,27 @@ idea).  When the figure is rendered, all of the artists are drawn to
 the **canvas**.  Most Artists are tied to an Axes; such an Artist
 cannot be shared by multiple Axes, or moved from one to another.
 
+.. _input_types:
+
+Types of inputs to plotting functions
+=====================================
+
+All of plotting functions expect `np.array` or `np.ma.masked_array` as
+input.  Classes that are 'array-like' such as `pandas` data objects
+and `np.matrix` may or may not work as intended.  It is best to
+convert these to `np.array` objects prior to plotting.
+
+For example, to covert a `pandas.DataFrame` ::
+
+  a = pandas.DataFrame(np.random.rand(4,5), columns = list('abcde'))
+  a_asndarray = a.values
+
+and to covert a `np.matrix` ::
+
+  b = np.matrix([[1,2],[3,4]])
+  b_asarray = np.asarray(b)
+
+
 
 .. _pylab:
 
