update installation instructions

content/install.rst

@@ -2,24 +2,42 @@
 Downloading and installing Kwant
 ================================
 
+Overview of available methods
+=============================
+
 The quickest and easiest way to install Kwant is using the prepared packages
 that are available for GNU/Linux (`Debian <#debian-and-derivatives>`_, `Ubuntu
 <#ubuntu-and-derivatives>`_, and their variants, `Arch Linux`_), `Mac OS X`_,
-and `Microsoft Windows`_.  It is possible to be notified about new releases of
-Kwant through an `announcement mailing list
-<community.html#announcements-of-new-releases>`_.
+and `Microsoft Windows`_.
+
+Like most Python packages, `Kwant can be also installed using pip
+<#automatic-installation-using-pip>`_.  (Note, however, that this will often
+result in a Kwant installation that runs significantly slower.)
 
 If no packages are available for the system you use, or if you would like to
 build Kwant from source for another reason (expert users may want to customize
-Kwant to use certain optimized versions of libraries), please consult the `full
-installation instructions
-<doc/1/pre/install.html#building-and-installing-from-source>`_ in the
-documentation.
+Kwant to use certain optimized versions of libraries), please consult the
+documentation on `how to install Kwant from source <doc/1/pre/install.html>`_.
+
+
+Python 3 or Python 2
+====================
+
+Before installing Kwant, one has to decide which Python version to use –
+Python 3 or Python 2.  `Python 3.0
+<https://docs.python.org/3/whatsnew/3.0.html>`_ was the first ever
+intentionally backwards incompatible Python release, i.e. scripts that target
+Python 2 will typically not run with Python 3 and above unchanged.
+
+Kwant releases up to 1.1 require Python 2.  Starting with release 1.2, we have
+`switched to Python 3 <http://kwant-project.org/doc/1/pre/whatsnew/1.2>`_.  We
+recommend to use the latest Kwant with Python 3.  Those who are stuck with
+Python 2 are invited to continue to use Kwant 1.1 which will be maintained for
+several years after 2015.
 
-The source code of released versions of Kwant is available for `download
-<http://downloads.kwant-project.org/kwant/>`_.  You can follow the development
-by browsing or cloning the `Git repository of Kwant
-<https://gitlab.kwant-project.org/kwant/kwant>`_.
+The instructions below assume Python 3.  They should be also valid for Python
+2 if all occurrences of ``python3``, ``pip3``, etc. are replaced by
+``python``, ``pip``.
 
 
 Debian and derivatives
@@ -48,7 +66,7 @@ The lines prefixed with ``sudo`` have to be run as root.
 3. Update the package data, and install Kwant::
 
        sudo apt-get update
-       sudo apt-get install python-kwant python-kwant-doc
+       sudo apt-get install python3-kwant python-kwant-doc
 
    The ``python-kwant-doc`` package is optional and installs the HTML
    documentation of Kwant in the directory ``/usr/share/doc/python-kwant-doc``.
@@ -61,13 +79,13 @@ surprisingly easy::
 
     sudo apt-get build-dep tinyarray
     apt-get source --compile tinyarray
-    sudo dpkg -i python-tinyarray_*.deb
+    sudo dpkg --install python3-tinyarray_*.deb
 
     sudo apt-get build-dep kwant
     apt-get source --compile kwant
-    sudo dpkg -i python-kwant_*.deb python-kwant-doc_*.deb
+    sudo dpkg --install python3-kwant_*.deb python-kwant-doc_*.deb
 
-This method should work for virtually all Debian-derived systems, even on exotic
+This method should work for all Debian-derived systems, even on exotic
 architectures.
 
 
@@ -78,7 +96,7 @@ Execute the following commands::
 
     sudo apt-add-repository ppa:kwant-project/ppa
     sudo apt-get update
-    sudo apt-get install python-kwant python-kwant-doc
+    sudo apt-get install python3-kwant python-kwant-doc
 
 This should provide Kwant for all versions of Ubuntu >= 12.04.  The HTML
 documentation will be installed locally in the directory
@@ -88,9 +106,12 @@ documentation will be installed locally in the directory
 Arch Linux
 ==========
 
-Arch install scripts for Kwant are kindly provided by Jörg Behrmann (formerly
-by Max Schlemmer).  To install, follow the `Arch User Repository installation
-instructions
+*(This section still targets Python 2 and needs to be updated for Python 3.)*
+
+‘Arch install scripts for Kwant
+<https://aur.archlinux.org/packages/python2-kwant/>‘_ are kindly provided by
+Jörg Behrmann (formerly by Max Schlemmer).  To install, follow the `Arch User
+Repository installation instructions
 <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_.
 Note that for checking the validity of the package you need to add the key
 used for signing to your user's keyring via::
@@ -113,6 +134,8 @@ Kwant and its dependencies both via the `homebrew <http://brew.sh>`_ and the
 Mac OS X: homebrew
 ==================
 
+*(This section needs to be updated for Python 3.)*
+
 homebrew is a recent addition to the package managers on Mac OS X. It is
 lightweight, tries to be as minimalistic as possible and give the user
 freedom than Macports. We recommend this option if you have no preferences.
@@ -182,6 +205,8 @@ Notes:
 Mac OS X: MacPorts
 ==================
 
+*(This section needs to be updated for Python 3.)*
+
 MacPorts is a full-fledged package manager that recreates a whole Linux-like
 environment on your Mac.
 
@@ -268,8 +293,8 @@ provided by Christoph Gohlke.  To install Kwant on Windows
 5. Reboot your computer.
 
 6. Download the necessary packages (with the ending ``.whl``) for your
-   operating system (32 or 64 bit) and Python version (e.g. ``cp27`` for Python
-   2.7) from the website of `Christoph Gohlke
+   operating system (32 or 64 bit) and Python version (e.g. ``cp34`` for Python
+   3.4) from the website of `Christoph Gohlke
    <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_.  For Kwant, we recommend to download at least `NumPy <http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy>`_, `SciPy <http://www.lfd.uci.edu/~gohlke/pythonlibs/#scipy>`_, `Matplotlib <http://www.lfd.uci.edu/~gohlke/pythonlibs/#matplotlib>`_, `Nose <http://www.lfd.uci.edu/~gohlke/pythonlibs/#nose>`_, `Tinyarray <http://www.lfd.uci.edu/~gohlke/pythonlibs/#tinyarray>`_, and `Kwant <http://www.lfd.uci.edu/~gohlke/pythonlibs/#kwant>`_ itself.
 
 7. Now open a command prompt with administrator rights, as described in
@@ -278,13 +303,52 @@ provided by Christoph Gohlke.  To install Kwant on Windows
 
    In this new command prompt window, execute ::
 
-       pip install <filename>
-
-   for each of the downloaded files (replacing ``<filename>`` with it).
+       pip3 install --no-deps *.whl
 
+   (This will install all the wheel-files in the current directory.)
    Now you are done, you can ``import kwant`` from within Python scripts.
 
-(Note that many other userful scientific packages are available in Gohlke’s
+(Note that many other useful scientific packages are available in Gohlke’s
 repository.  For example, you might want to install `IPython
 <http://www.lfd.uci.edu/~gohlke/pythonlibs/#ipython>`_ and its various
 dependencies so that you can use the `IPython notebook <http://ipython.org/notebook.html>`_.)
+
+
+Automatic installation using ``pip``
+====================================
+
+The most recent stable version of Kwant can be downloaded and installed
+directly from the `Python package index <https://pypi.python.org/>`_ using
+Python’s “pip“ tool::
+
+    sudo pip3 install kwant
+
+Pip can be also used to directly install the most recent development version
+of Kwant directly from the Git repository::
+
+    sudo pip3 install git+https://gitlab.kwant-project.org/kwant/kwant.git
+
+Each of the above commands will perform a system-wide install (to
+``/usr/local`` on Unix).  Type ``pip3 help install`` for installation options
+and see `pip documentation <https://pip.readthedocs.org/>`_ for a detailed
+description of ``pip``.
+
+Note that ``pip`` will not install any non-Python dependencies such as `MUMPS
+<http://graal.ens-lyon.fr/MUMPS/>`_.  These need to be installed in some other
+way.  As an example, on a Debian or Ubuntu system, the following command will
+install the non-Python prerequisites of Kwant::
+
+    sudo apt-get install gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
+
+The Kwant build scripts should find libraries that have been installed in the
+above way automatically.  This will be signaled at the end of the build
+process as follows::
+
+    ******************************** Build summary ********************************
+    Default LAPACK and BLAS
+    Auto-configured MUMPS
+    *******************************************************************************
+
+On other platforms MUMPS will not be linked against.  If prepared packages are
+not an option, the build process must be `configured manually
+<doc/1/pre/install.html#build-configuration>`_.