I assume that most people encounter the tutorial example scripts by
reading the documentation, and not by viewing the tutorial subdirectory
of a checked-out Kwant source.

That's the motivation for moving all the manipulations of tutorial
scripts from setup.py to doc/Makefile.  Previously, a successful 'make
html' would require a preceding execution of 'setup.py build_tut'.  Now,
a simple 'make html' is enough.

While at it, I reorganized where the example scripts and their outputs
are stored.  Everything is now in 'doc/source/code' with its three
subdirectories 'download' (to be shown to readers), 'include' (with
include markers), and 'figure' (figure generation & figures).  This
organization is clearer and also makes the generation of figures
separate from the tutorial.

lowercase FAQ.rst, FAQ.py, etc., give meaningful names to labels,
and stop building an user-visible tutorial/faq.py

Our baseline is Debian stable (Jessie) where possible.  The only
dependency that cannot be satisfied is sympy; Debian stable does not
have a Python 3 package for this.  We set the required sympy version to
that present in Ubuntu 16.04 LTS.

This allows to provide a helpful error message when someone tries to
import Kwant with Python 2.

Note that I moved the version code into a module of its own:
kwant.version.  The rationale is to separate this code from unrelated
stuff in kwant._common that requires various external libs.  The
kwant.version module should work on its own without any third-party
libraries.

Previously the testing/importing 'continuum' would fail if sympy was not
installed. Now we do the following:

    * add sympy as an optional dependency in 'extras_require'
    * force pytest to ignore tests in packages that have uninstalled
      dependencies by defining a hook in 'conftest.py'
    * use the 'class as a module' hack when importing 'continuum'.
      When sympy is not installed the continuum module will be replaced
      with an instance of 'ExtensionUnavailable' that will raise a runtime
      error on attribute access.
    * no warning is raised if sympy is not installed (it is an
      optional dependency).

This reverts commit e34b4b73.

It has the same problems as setup_requires.

Packages that are mentionned there are installed in a way that bypasses
pip:
https://pip.pypa.io/en/stable/user_guide/?highlight=setup_requires#installation-bundles

These prefixes were visible, for example when invoking
"./setup.py --help build".

Before we used the include_dir argument to setup(), but this caused problems:
kwant/kwant#48

Commit a8b0463e turned out to be a bad
idea: unlike on Debian, on many platforms the numpy headers are not
available in the default include path.

    1. Now can be compiled without MUMPS
       (previously exception was thrown)
    2. Gives sensible error message for Git install,
       but without installed Cython.

With the reorganization of setup.py, most constants are now used in a
single place.  It is clearer and simpler to have them there.

The CYTHON_TRACE macro can be now set in the build.conf file.

All C extensions are now treated on equal footing and can be configured
in "build.conf".  All the options known by Extension may be set now for
any extension individually and for all of them together (using the
[DEFAULT] section).

This reduces the number of global variables and makes the code easier to
understand.

The removed code predates "build.conf" and should not be necessary on
most (all?) platforms.  Should numpy be missing in the include path, it
can be added using "build.conf".

If this change turns out to cause problems, we can always revert it.