Adds tree encoding and decoding functions.

This commit makes several additions. The main additions are two
encoding/decoding schemes for trees, the nested tuple and Prüfer
sequence schemes. These appear in a new module,
`networkx.algorithms.tree.coding`.

These encoding/decoding functions required implementing a function for
joining subtrees at a root node, which appears as the `join` function in
a new module, `networkx.algorithms.tree.operations`.

Finally, the encoding/decoding schemes suggest a simple implementation
for generating a uniformly random tree. The random tree generator first
generates a random Prüfer sequence, then converts that sequence to the
corresponding tree. This `random_tree` function appears in a new module,
`networkx.generators.tree`.

1 files changed, 14 insertions, 3 deletions

diff --git a/networkx/algorithms/traversal/breadth_first_search.py b/networkx/algorithms/traversal/breadth_first_search.py
index 6166ce0b..c8be79a9 100644
--- a/networkx/algorithms/traversal/breadth_first_search.py
+++ b/networkx/algorithms/traversal/breadth_first_search.py
@@ -32,9 +32,20 @@ def bfs_edges(G, source, reverse=False):
 
     Examples
     --------
-    >>> G = nx.path_graph(3)
-    >>> print(list(nx.bfs_edges(G,0)))
-    [(0, 1), (1, 2)]
+    To get the edges in a breadth-first search::
+
+        >>> G = nx.path_graph(3)
+        >>> list(nx.bfs_edges(G, 0))
+        [(0, 1), (1, 2)]
+
+    To get the nodes in a breadth-first search order::
+
+        >>> G = nx.path_graph(3)
+        >>> root = 2
+        >>> edges = nx.bfs_edges(G, root)
+        >>> nodes = [root] + [v for u, v in edges]
+        >>> nodes
+        [2, 1, 0]
 
     Notes
     -----