matplotlib
diff --git a/‎doc/faq/installing_faq.rst
Copy file name to clipboardExpand all lines: doc/faq/installing_faq.rst
+94-172Lines changed: 94 additions & 172 deletions b/‎doc/faq/installing_faq.rst
Copy file name to clipboardExpand all lines: doc/faq/installing_faq.rst
+94-172Lines changed: 94 additions & 172 deletions
@@ -19,18 +19,10 @@ The first thing to try is a :ref:`clean install <clean-install>` and see if
 that helps.  If not, the best way to test your install is by running a script,
 rather than working interactively from a python shell or an integrated
 development environment such as :program:`IDLE` which add additional
-complexities. Open up a UNIX shell or a DOS command prompt and cd into a
-directory containing a minimal example in a file. Something like
-:file:`simple_plot.py` for example::
+complexities. Open up a UNIX shell or a DOS command prompt and run, for
+example::
 
-  import matplotlib.pyplot as plt
-  fig, ax = plt.subplots()
-  ax.plot([1,2,3])
-  plt.show()
-
-and run it with::
-
-  python simple_plot.py --verbose-helpful
+   python -c "from pylab import *; plot(); show()" --verbose-helpful
 
 This will give you additional information about which backends matplotlib is
 loading, version information, and more. At this point you might want to make
@@ -42,127 +34,46 @@ If you are still having trouble, see :ref:`reporting-problems`.
 
 .. _clean-install:
 
-How to completely remove matplotlib
+How to completely remove Matplotlib
 ===================================
 
-Occasionally, problems with matplotlib can be solved with a clean
-installation of the package.
-
-The process for removing an installation of matplotlib depends on how
-matplotlib was originally installed on your system. Follow the steps
-below that goes with your original installation method to cleanly
-remove matplotlib from your system.
-
-Source install
---------------
-
-Unfortunately::
-
-    python setup.py clean
+Occasionally, problems with Matplotlib can be solved with a clean
+installation of the package.  In order to fully remove an installed Matplotlib:
 
-does not properly clean the build directory, and does nothing to the
-install directory.  To cleanly rebuild:
-
-1. Delete the caches from your :ref:`.matplotlib configuration directory
+1. Delete the caches from your :ref:`Matplotlib configuration directory
    <locating-matplotlib-config-dir>`.
 
-2. Delete the ``build`` directory in the source tree.
-
-3. Delete any matplotlib directories or eggs from your :ref:`installation
+2. Delete any Matplotlib directories or eggs from your :ref:`installation
    directory <locating-matplotlib-install>`.
 
-How to Install
-==============
-
-.. _install-from-git:
-
-Source install from git
------------------------
-
-Clone the main source using one of::
-
-   git clone git@github.com:matplotlib/matplotlib.git
-
-or::
-
-   git clone git://github.com/matplotlib/matplotlib.git
-
-and build and install as usual with::
-
-  > cd matplotlib
-  > python setup.py install
-
-.. 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 all of the
-    build dependencies, which will make building from source easier.
-
-
-If you want to be able to follow the development branch as it changes
-just replace the last step with (make sure you have **setuptools**
-installed)::
-
-  > python setup.py develop
-
-This creates links in the right places and installs the command
-line script to the appropriate places.
-
-.. note::
-   Mac OSX users please see the :ref:`build_osx` guide.
-
-   Windows users please see the :ref:`build_windows` guide.
-
-Then, if you want to update your matplotlib at any time, just do::
-
-  > git pull
-
-When you run `git pull`, if the output shows that only Python files have been
-updated, you are all set. If C files have changed, you need to run the `python
-setup.py develop` command again to compile them.
-
-There is more information on :ref:`using git <using-git>` in
-the developer docs.
-
-
 Linux Notes
 ===========
 
-Because most Linux distributions use some sort of package manager,
-we do not provide a pre-built binary for the Linux platform.
-Instead, we recommend that you use the "Add Software" method for
-your system to install matplotlib. This will guarantee that everything
-that is needed for matplotlib will be installed as well.
+We recommend that you use your distribution's package manager to install
+Matplotlib.  This will guarantee that Matplotlib's dependencies will be
+installed as well.
+
+If, for some reason, you can not use the package manager, you may use the
+manylinux wheels available on PyPI::
 
-If, for some reason, you can not use the package manager, Linux usually
-comes with at least a basic build system. Follow the :ref:`instructions
-<install-from-git>` found above for how to build and install matplotlib.
+   python -mpip install matplotlib
 
+or :ref:`build Matplotlib from source <install-from-git>`.
 
-OS-X Notes
-==========
+OSX Notes
+=========
 
 .. _which-python-for-osx:
 
-Which python for OS X?
-----------------------
+Which python for OSX?
+---------------------
 
-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
+Apple ships OSX 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 (see `system python packages`_).  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.  One convenient way to
+installing libraries such as NumPy and Matplotlib.  One 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:
 
@@ -242,20 +153,15 @@ For Python 2.7::
 
     pip2 install matplotlib
 
-For Python 3.4::
+For Python 3::
 
     pip3 install matplotlib
 
-You might also want to install IPython; we recommend you install IPython with
-the IPython notebook option, like this:
+You might also want to install IPython or the Jupyter notebook (``pip install
+ipython``, ``pip install notebook``; for Macports and Homebrew, adapt the
+command as above).
 
-* 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]``
-
-Pip problems
+pip problems
 ^^^^^^^^^^^^
 
 If you get errors with pip trying to run a compiler like ``gcc`` or ``clang``,
@@ -264,51 +170,10 @@ then the first thing to try is to `install xcode
 retry the install.  If that does not work, then check
 :ref:`reporting-problems`.
 
-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 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.6.dmg`.
-The name of the installer depends on the versions of python and matplotlib it
-was built for, and the version of OSX that the matching Python.org installer
-was built for.  For example, if the mathing Python.org Python installer was
-built for OSX 10.6 or greater, the dmg file will end in ``-macosx10.6.dmg``.
-You need to download this disk image file, 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.6.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/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
+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::
 
   python2.7 -c 'import matplotlib; print matplotlib.__version__, matplotlib.__file__'
@@ -321,7 +186,7 @@ with one of these commands at the Terminal.app command line::
 
   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
+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::
 
@@ -340,14 +205,71 @@ or::
 
 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 let us
-know: see :ref:`reporting-problems`.
+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 :ref:`let us know
+<reporting-problems>`.
 
 Windows Notes
 =============
 
 See :ref:`installing_windows`.
+
+.. _install-from-git:
+
+Install from source
+===================
+
+Clone the main source using one of::
+
+   git clone git@github.com:matplotlib/matplotlib.git
+
+or::
+
+   git clone git://github.com/matplotlib/matplotlib.git
+
+and build and install as usual with::
+
+   cd matplotlib
+   pip install .
+
+.. 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 all of the build
+   dependencies, which will make building from source easier.
+
+If you want to be able to follow the development branch as it changes
+just replace the last step with::
+
+   pip install -e .
+
+This creates links and installs the command line script in the appropriate
+places.
+
+.. note::
+   OSX users please see the :ref:`build_osx` guide.
+
+   Windows users please see the :ref:`build_windows` guide.
+
+Then, if you want to update your matplotlib at any time, just do::
+
+   git pull
+
+When you run ``git pull``, if the output shows that only Python files have
+been updated, you are all set. If C files have changed, you need to run ``pip
+install -e .`` again to compile them.
+
+There is more information on :ref:`using git <using-git>` in the developer
+docs.