Add examples and minor documentaion refactor for operators/binary.py (#5099)

* Add examples and minor refactor

* Fix intersection example

* Fix difference example

* Fix difference example take 2

* Remove example imports and update union example
Co-authored-by: Dan Schult <dschult@colgate.edu>

* Fix some errors

* Improve union docstring

* Add back union name kwarg

1 files changed, 77 insertions, 4 deletions

diff --git a/networkx/algorithms/operators/binary.py b/networkx/algorithms/operators/binary.py
index d2626e7a..a3bbab36 100644
--- a/networkx/algorithms/operators/binary.py
+++ b/networkx/algorithms/operators/binary.py
@@ -17,14 +17,15 @@ __all__ = [
 def union(G, H, rename=(None, None), name=None):
     """Return the union of graphs G and H.
 
-    Graphs G and H must be disjoint, otherwise an exception is raised.
+    Graphs G and H must be disjoint after the renaming takes place,
+    otherwise an exception is raised.
 
     Parameters
     ----------
     G,H : graph
        A NetworkX graph
 
-    rename : bool , default=(None, None)
+    rename : tuple , default=(None, None)
        Node names of G and H can be changed by specifying the tuple
        rename=('G-','H-') (for example).  Node "u" in G is then renamed
        "G-u" and "v" in H is renamed "H-v".
@@ -48,6 +49,16 @@ def union(G, H, rename=(None, None), name=None):
     to the union graph.  If a graph attribute is present in both
     G and H the value from H is used.
 
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (1, 2)])
+    >>> H = nx.Graph([(0, 1), (0, 3), (1, 3), (1, 2)])
+    >>> U = nx.union(G, H, rename=("G", "H"))
+    >>> U.nodes
+    NodeView(('G0', 'G1', 'G2', 'H0', 'H1', 'H3', 'H2'))
+    >>> U.edges
+    EdgeView([('G0', 'G1'), ('G0', 'G2'), ('G1', 'G2'), ('H0', 'H1'), ('H0', 'H3'), ('H1', 'H3'), ('H1', 'H2')])
+
     See Also
     --------
     disjoint_union
@@ -89,6 +100,18 @@ def disjoint_union(G, H):
     Graph, edge, and node attributes are propagated from G and H
     to the union graph.  If a graph attribute is present in both
     G and H the value from H is used.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (1, 2)])
+    >>> H = nx.Graph([(0, 3), (1, 2), (2, 3)])
+    >>> G.nodes[0]["key1"] = 5
+    >>> H.nodes[0]["key2"] = 10
+    >>> U = nx.disjoint_union(G, H)
+    >>> U.nodes(data=True)
+    NodeDataView({0: {'key1': 5}, 1: {}, 2: {}, 3: {'key2': 10}, 4: {}, 5: {}, 6: {}})
+    >>> U.edges
+    EdgeView([(0, 1), (0, 2), (1, 2), (3, 4), (4, 6), (5, 6)])
     """
     return nx.disjoint_union_all([G, H])
 
@@ -123,6 +146,16 @@ def intersection(G, H):
     >>> R = G.copy()
     >>> R.remove_nodes_from(n for n in G if n not in H)
     >>> R.remove_edges_from(e for e in G.edges if e not in H.edges)
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (1, 2)])
+    >>> H = nx.Graph([(0, 3), (1, 2), (2, 3)])
+    >>> R = nx.intersection(G, H)
+    >>> R.nodes
+    NodeView((0, 1, 2))
+    >>> R.edges
+    EdgeView([(1, 2)])
     """
     return nx.intersection_all([G, H])
 
@@ -135,7 +168,7 @@ def difference(G, H):
     Parameters
     ----------
     G,H : graph
-       A NetworkX graph.  G and H must have the same node sets.
+       A NetworkX graph. G and H must have the same node sets.
 
     Returns
     -------
@@ -152,6 +185,16 @@ def difference(G, H):
     >>> H = nx.path_graph(5)
     >>> R = G.copy()
     >>> R.remove_nodes_from(n for n in G if n in H)
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (1, 2), (1, 3)])
+    >>> H = nx.Graph([(0, 1), (1, 2), (0, 3)])
+    >>> R = nx.difference(G, H)
+    >>> R.nodes
+    NodeView((0, 1, 2, 3))
+    >>> R.edges
+    EdgeView([(0, 2), (1, 3)])
     """
     # create new graph
     if not G.is_multigraph() == H.is_multigraph():
@@ -189,6 +232,16 @@ def symmetric_difference(G, H):
     -----
     Attributes from the graph, nodes, and edges are not copied to the new
     graph.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (1, 2), (1, 3)])
+    >>> H = nx.Graph([(0, 1), (1, 2), (0, 3)])
+    >>> R = nx.symmetric_difference(G, H)
+    >>> R.nodes
+    NodeView((0, 1, 2, 3))
+    >>> R.edges
+    EdgeView([(0, 2), (0, 3), (1, 3)])
     """
     # create new graph
     if not G.is_multigraph() == H.is_multigraph():
@@ -246,6 +299,16 @@ def compose(G, H):
     For MultiGraphs, the edges are identified by incident nodes AND edge-key.
     This can cause surprises (i.e., edge `(1, 2)` may or may not be the same
     in two graphs) if you use MultiGraph without keeping track of edge keys.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2)])
+    >>> H = nx.Graph([(0, 1), (1, 2)])
+    >>> R = nx.compose(G, H)
+    >>> R.nodes
+    NodeView((0, 1, 2))
+    >>> R.edges
+    EdgeView([(0, 1), (0, 2), (1, 2)])
     """
     return nx.compose_all([G, H])
 
@@ -263,7 +326,7 @@ def full_join(G, H, rename=(None, None)):
     G, H : graph
        A NetworkX graph
 
-    rename : bool , default=(None, None)
+    rename : tuple , default=(None, None)
        Node names of G and H can be changed by specifying the tuple
        rename=('G-','H-') (for example).  Node "u" in G is then renamed
        "G-u" and "v" in H is renamed "H-v".
@@ -288,6 +351,16 @@ def full_join(G, H, rename=(None, None)):
     to the union graph.  If a graph attribute is present in both
     G and H the value from H is used.
 
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2)])
+    >>> H = nx.Graph([(3, 4)])
+    >>> R = nx.full_join(G, H, rename=("G", "H"))
+    >>> R.nodes
+    NodeView(('G0', 'G1', 'G2', 'H3', 'H4'))
+    >>> R.edges
+    EdgeView([('G0', 'G1'), ('G0', 'G2'), ('G0', 'H3'), ('G0', 'H4'), ('G1', 'H3'), ('G1', 'H4'), ('G2', 'H3'), ('G2', 'H4'), ('H3', 'H4')])
+
     See Also
     --------
     union