* buildout.cfg: Remove redundancy

Share the eggs definition between the the online and offline tests.

* Remove redundant code

Trying to insert `self._dest` in `self._path`  in `Installer.install()`
is unnecessary since:

 * it's already done in `__init__()`

 * nothing changes either `self._path` or `self._dest` during the
   lifetime of `Installer`

Remove `Installer._load_dist(self, dist)` since it has never been
used in the whole history of Buildout.

Finally, simplify the interface to `._get_dist()` and  `_call_easy_install()`:

All callers to `._get_dist()` add the resulting dist to the WorkingSet. No
reason to do it in `._get_dist()` or to pass the `ws` into
`._call_easy_install()`.

* Be stricter when adding setuptools as requirements

Only do it for namespace package dists that actually need it. I.e. those
that use `pkg_resources.declare_namespace()` instead of
`pkg_util.extend_path()` or PEP 420.

* easy_install: `eggs-directory` may contain more than eggs

Modify the `easy_install.Installer` class to locate not only eggs, but
anything that has a `.dist-info` inside `._dest` (i.e. the Buildout
`eggs-directory`).

This makes it easier for extensions like `buildout.wheel` to add non eggs
inside it: by installing a distribution inside a subdirectory of `._dest` as if
that subdirectory was `site-packages`, you can later locate that
distribution with the Installer.

Conversely, make sure any distribution found in a direct child of `.dest` is
treated as if it was an `egg` distribution (as opposed to a develop
distribution or a site-packages distribution).

All access to `Installer._path` and all access that modifies `._env` is now
done through `Installer` methods, so that Buildout extensions can install
subclasses of `Installer` that alter their behaviour.

* Refactor `_get_dist()` and `_call_easy_install()`

Move the actual invocation of `easy_install` to a module global function
`call_easy_install()`. Simplify its signature so it's simpler to
override in Buildout extensions.

Refactor `._get_dist()` and remove all unpack/install logic into
`_move_to_eggs_dir_and_compile()`, bypassing
`Installer._call_easy_install()`.

`._get_dist()` now calls directly `call_easy_install()` instead. But
only as a fallback to a dictionary lookup of filename extensions to
distribution unpacking methods like:

 - `.egg`: `unpack_egg()`
 - `.whl`: `unpack_wheel()`

This will make it easier for extensions to add support to new dist
formats.

* Added docs for the annotate and setup commands. (#362)

Optimizing topic

(I hope at some point this can go away because
https://github.com/buildout/buildout/issues/355)

* Added reference documentation for command-line options

- Intentionally didn't document -o, -O and -n

  Offline mode is an attractive nuisance.

  -n is unlikely to be needed and can be spelled newest=true

- Removed -o, -O and -n from command help.

- Sorted options alphabetically in the reference doc and command help.

- Removed documentation of the log-level option.  It just confuses things.
  I seriously doubt that anyone uses it.

* Added configuration-file syntax reference

Added missing section on conditional sections

Fortunately, I was able to move and update the not-bad doctest here,
because it was more doc than test.

easy_install: moar loggin' for fetchin'

Make it clear from where we're fetching a dist that we don't have
installed, reporting the specific URL or the path from inside the
download cache.

* Added topic on reusing option values and buildout config options reference

* unbroke capitalization

* added another todo

But maybe I should stop doing this because sphinx tells me about
missing references.

* note that paths are whitespace separated.

* fixed some minor wording bugs.

* Added a hidden test to check my understanding of interaction with install-from-cache

* Clarify modes and semantics of extends-cache

* emphasize that in newst mode, we always download configuration

* expanded on logging control

* clarified socket-timeout

* spelling and it's

* simplify user-default example

* warn about unpinning when using develop eggs

* discuss unpinning

* explain why unpinning with empty pin is useful.

* reverted examples to use longer more explict forms

* typos

* Added tests for variables-extending-and-substitutions.rst

Also added more test helpers.

* Use bobo rather than ZEO in tests of docs

To make the tests more lightweight, because bobo is much smaller.

To allow people without the ability to build extensions to follow along.

* Fixed: test index (used for testing docs) was set to wrong path

* I want to see which tests are being run

History

Bootstrapping topic

windows: scripts are implemented with 2 files, avoid burping on that

Motivation, history and Python packaging topic

draft getting started

Start on new docs

Update tox versions according to Makefile

For some reason, installation is taking insanely long for Python 2
(10x Py3). NFC, but this bears further investication, given that it's just copying eggs, except pyc re-compilation to get correct path.

- Now wait up to 99 seconds for builds to complete.

- handle build timeout by printing output (rather than a failing
  assertion, now that we know it can happen).

- Got rid of the broken out() function.

there is an error.  I'd been trying to avoid writing a file, but that
made things too complicated.  I've seen some hard to reproduce test
failures that make turning on debugging in response to a failure
impractical.  Hopefully, if we get a test failure now, we'll be able
to see WTF.