This commit combines two changes. First, it moves the module
`networkx.generators.hybrid` to `networkx.algorithms.hybrid` (and moves
the corresponding test modules as well). Second, it adds missing
documentation to the functions in that module.

This implements vertex and edge contraction as functions that return new
graph objects with the specified vertices or edge contracted.

This fixes issue #1057.

The tests expected the ouput of nx.non_edges to preserve a certain
order. This is no longer the case. The change also removes some code
duplication in the test suite.

Added example of an efficient function to compute k shortest paths
in the example section of shortest_simple_paths docstrings. Added
more tests, I think all relevant code for this function is covered
now.

I've removed the asserts, fixed the inability to use an arbitrary
edge attribute as a weight, and speeded it up by computing
separatetly the length/cost of the root and then adding it
to the newly found partial path instead of computing the
lenth/cost of the whole path when we push it to PathBuffer.

This function is based on Yen's algorithm for finding k shortest paths.
It generates all simple paths between source and target starting from
the shortest one. See #762 and #793 for prior work on this and discussion.

This implementation is based on Andrey's work on #762. It generalizes his
approach there to the weighted case, as in Greg's implementation posted
on #793.

Regarding the discussion on #762 about how to do the filtering of nodes
and edges efficiently, this PR adds private modifications of the functions
`bidirectional_shortest_path` and `bidirectional_dijkstra` (that accept
containers with nodes and edges to exclude during the SP search) for its
exclusive use.

This still needs work, especially on documentation and tests. I'm pushing
it so we can have the discussion with the code available.

One thing to discuss is whether or not to include an one liner function
to get the k shortest paths. Could be something like this:

```python
from itertools import islice
def k_shortest_paths(G, source, target, k, weight=None):
        return list(islice(nx.shortest_simple_paths(G, source, target, weight=weight), k))
```

I think that, given that `all_simple_paths` is way faster in computing
all paths, the principal use of `shortest_simple_paths` will be to get
the k best/shortest paths. So it will be a more user friendly interface
if we add it. However, we could also add this function as example in the
`shortest_simple_paths` docstring. I'm ok either way. Thoughts?