This fixes #392.

Previously under Python 3 (probably prior to 3.6, when dicts became
ordered by default) or under Python 2 with ``-R`` or
``PYTHONHASHSEED=random`` the results were undefined because dict
iteration order is undefined.

The value being sorted is complex and defined by
pkg_resources.Distribution:

```    @property
    def hashcmp(self):
        return (
            self.parsed_version,
            self.precedence,
            self.key,
            _remove_md5_fragment(self.location),
            self.py_version or '',
            self.platform or '',
        )

    def __hash__(self):
        return hash(self.hashcmp)

    def __lt__(self, other):
        return self.hashcmp < other.hashcmp
...
```

[ci skip]

[ci skip]

verbose mode and select sections for annotate command

avoid --section flag

--verbose allows, among others, to find out which values are overridden
when extending cfg files

--section allows to focus on a specific section

[ci skip]

[ci skip]

It's not present in older setuptools versions.

It seems not to be needed since `pkg_resources.Environment.add()` will
sort dists in each project_name according to their version anyway.

[ci skip]

[ci skip]

That was broken because the docs are no longer in the long description.

[ci skip]

[ci skip]

* Document UserError

* Additional resources.

* briefly explain extensions

Later, we'll probably discuss how to develop them, probably in a separate document.

* move old changes to HISTORY.rst

* Cut over to new docs!

* Moved the meta-recipe test over to the manual.

It was already written as documentation using manuel.

The `unpack_wheel` was blindly trusting the result of `wheel_to_egg()`
and possibly laying zipped eggs in `eggs-directory`.

Fix it to always unpack the result of `wheel_to_egg()` instead.

* Make the Buildout helper class useful for testing recipes.

* Move run_buildout_in_process to testing because recipe integration tests may find it useful.

* Added support for special implication syntax ``=>``

* added <part-dependencies> support

* 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.