Merge pull request #1677 from MridulS/docupiter_refactor

Update classes docs

4 files changed, 69 insertions, 38 deletions

diff --git a/networkx/classes/digraph.py b/networkx/classes/digraph.py
index ec93e5bc..25a478c5 100644
--- a/networkx/classes/digraph.py
+++ b/networkx/classes/digraph.py
@@ -156,7 +156,8 @@ class DiGraph(Graph):
     **Reporting:**
 
     Simple graph information is obtained using methods.
-    Iterator versions of many reporting methods exist for efficiency.
+    Reporting methods usually return iterators instead of containers
+    to reduce memory usage.
     Methods exist for reporting nodes(), edges(), neighbors() and degree()
     as well as the number of nodes and edges.
 
@@ -785,6 +786,7 @@ class DiGraph(Graph):
 
         See Also
         --------
+        in_edges, out_edges
 
         Notes
         -----
@@ -864,10 +866,10 @@ class DiGraph(Graph):
 
 
     def degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, degree) and degree for single node.
+        """Return an iterator for (node, degree) or degree for single node.
 
         The node degree is the number of edges adjacent to the node.
-        This function returns the degree for a single node and an iterator
+        This function returns the degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -883,8 +885,11 @@ class DiGraph(Graph):
 
         Returns
         -------
+        If a single node is requested
         deg:
-            Degree of the node, if a single node is passed as argument.
+            Degree of the node
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, degree).
 
@@ -931,10 +936,10 @@ class DiGraph(Graph):
 
 
     def in_degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, in-degree) and in-degree for single node.
+        """Return an iterator for (node, in-degree) or in-degree for single node.
 
         The node in-degree is the number of edges pointing in to the node.
-        This function returns the in-degree for a single node and an iterator
+        This function returns the in-degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -950,8 +955,11 @@ class DiGraph(Graph):
 
         Returns
         -------
+        If a single node is requested
         deg:
-            In-degree of the node, if a single node is passed as argument.
+            In-degree of the node
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, in-degree).
 
@@ -996,10 +1004,10 @@ class DiGraph(Graph):
 
 
     def out_degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, out-degree) and out-degree for single node.
+        """Return an iterator for (node, out-degree) or out-degree for single node.
 
         The node out-degree is the number of edges pointing out of the node.
-        This function returns the out-degree for a single node and an iterator
+        This function returns the out-degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -1015,8 +1023,11 @@ class DiGraph(Graph):
 
         Returns
         -------
+        If a single node is requested
         deg:
-            Out-degree of the node, if a single node is passed as argument.
+            Out-degree of the node
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, out-degree).
 
diff --git a/networkx/classes/graph.py b/networkx/classes/graph.py
index 7204167a..d2ce8ad4 100644
--- a/networkx/classes/graph.py
+++ b/networkx/classes/graph.py
@@ -167,7 +167,8 @@ class Graph(object):
     **Reporting:**
 
     Simple graph information is obtained using methods.
-    Iterator versions of many reporting methods exist for efficiency.
+    Reporting methods usually return iterators instead of containers
+    to reduce memory usage.
     Methods exist for reporting nodes(), edges(), neighbors() and degree()
     as well as the number of nodes and edges.
 
@@ -1020,16 +1021,6 @@ class Graph(object):
         NetworkXError
             If the node n is not in the graph.
 
-        Notes
-        -----
-        It is usually more convenient (and faster) to access the
-        adjacency dictionary as G[n]:
-
-        >>> G = nx.Graph()   # or DiGraph, MultiGraph, MultiDiGraph, etc
-        >>> G.add_edge('a','b',weight=7)
-        >>> G['a']
-        {'b': {'weight': 7}}
-
         Examples
         --------
         >>> G = nx.Graph()   # or DiGraph, MultiGraph, MultiDiGraph, etc
@@ -1039,8 +1030,13 @@ class Graph(object):
 
         Notes
         -----
-        It is faster to use the idiom "in G[0]", e.g.
+        It is usually more convenient (and faster) to access the
+        adjacency dictionary as ``G[n]``:
 
+        >>> G = nx.Graph()   # or DiGraph, MultiGraph, MultiDiGraph, etc
+        >>> G.add_edge('a', 'b', weight=7)
+        >>> G['a']
+        {'b': {'weight': 7}}
         >>> G = nx.path_graph(4)
         >>> [n for n in G[0]]
         [1]
@@ -1195,10 +1191,10 @@ class Graph(object):
         return iter(self.adj.items())
 
     def degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, degree) and degree for single node.
+        """Return an iterator for (node, degree) or degree for single node.
 
         The node degree is the number of edges adjacent to the node.
-        This function returns the degree for a single node and an iterator
+        This function returns the degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -1214,8 +1210,11 @@ class Graph(object):
 
         Returns
         -------
+        If a single node is requested
         deg:
-            Degree of the node, if a single node is passed as argument.
+            Degree of the node
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, degree).
 
diff --git a/networkx/classes/multidigraph.py b/networkx/classes/multidigraph.py
index 1623502b..654ca08e 100644
--- a/networkx/classes/multidigraph.py
+++ b/networkx/classes/multidigraph.py
@@ -166,7 +166,8 @@ class MultiDiGraph(MultiGraph,DiGraph):
     **Reporting:**
 
     Simple graph information is obtained using methods.
-    Iterator versions of many reporting methods exist for efficiency.
+    Reporting methods usually return iterators instead of containers
+    to reduce memory usage.
     Methods exist for reporting nodes(), edges(), neighbors() and degree()
     as well as the number of nodes and edges.
 
@@ -459,6 +460,9 @@ class MultiDiGraph(MultiGraph,DiGraph):
         >>> list(G.edges(0))
         [(0, 1)]
 
+        See Also
+        --------
+        in_edges, out_edges
         """
         if nbunch is None:
             nodes_nbrs = self.adj.items()
@@ -530,10 +534,10 @@ class MultiDiGraph(MultiGraph,DiGraph):
 
 
     def degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, degree) and degree for single node.
+        """Return an iterator for (node, degree) or degree for single node.
 
         The node degree is the number of edges adjacent to the node.
-        This function returns the degree for a single node and an iterator
+        This function returns the degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -549,11 +553,18 @@ class MultiDiGraph(MultiGraph,DiGraph):
 
         Returns
         -------
+        If a single nodes is requested
         deg:
-            Degree of the node, if a single node is passed as argument.
+            Degree of the node
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, degree).
 
+        See Also
+        --------
+        out_degree, in_degree
+
         Examples
         --------
         >>> G = nx.MultiDiGraph()
@@ -606,10 +617,10 @@ class MultiDiGraph(MultiGraph,DiGraph):
         return d_iter()
 
     def in_degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, in-degree) and in-degree for single node.
+        """Return an iterator for (node, in-degree) or in-degree for single node.
 
         The node in-degree is the number of edges pointing in to the node.
-        This function returns the in-degree for a single node and an iterator
+        This function returns the in-degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -625,8 +636,11 @@ class MultiDiGraph(MultiGraph,DiGraph):
 
         Returns
         -------
+        If a single node is requested
         deg:
-            Degree of the node, if a single node is passed as argument.
+            Degree of the node
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, in-degree).
 
@@ -673,10 +687,10 @@ class MultiDiGraph(MultiGraph,DiGraph):
         return d_iter()
 
     def out_degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, out-degree) and out-degree for single node.
+        """Return an iterator for (node, out-degree) or out-degree for single node.
 
         The node out-degree is the number of edges pointing out of the node.
-        This function returns the out-degree for a single node and an iterator
+        This function returns the out-degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -692,8 +706,11 @@ class MultiDiGraph(MultiGraph,DiGraph):
 
         Returns
         -------
+        If a single node is requested
         deg:
-            Degree of the node, if a single node is passed as argument.
+            Degree of the node
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, out-degree).
 
diff --git a/networkx/classes/multigraph.py b/networkx/classes/multigraph.py
index 32050fb6..232a0d15 100644
--- a/networkx/classes/multigraph.py
+++ b/networkx/classes/multigraph.py
@@ -167,7 +167,8 @@ class MultiGraph(Graph):
     **Reporting:**
 
     Simple graph information is obtained using methods.
-    Iterator versions of many reporting methods exist for efficiency.
+    Reporting methods usually return iterators instead of containers
+    to reduce memory usage.
     Methods exist for reporting nodes(), edges(), neighbors() and degree()
     as well as the number of nodes and edges.
 
@@ -721,10 +722,10 @@ class MultiGraph(Graph):
             return default
 
     def degree(self, nbunch=None, weight=None):
-        """Return an iterator for (node, degree) and degree for single node.
+        """Return an iterator for (node, degree) or degree for single node.
 
         The node degree is the number of edges adjacent to the node.
-        This function returns the degree for a single node and an iterator
+        This function returns the degree for a single node or an iterator
         for a bunch of nodes or if nothing is passed as argument.
 
         Parameters
@@ -740,8 +741,11 @@ class MultiGraph(Graph):
 
         Returns
         -------
+        If a single node is requested
         deg:
             Degree of the node, if a single node is passed as argument.
+
+        OR if multiple nodes are requested
         nd_iter : an iterator
             The iterator returns two-tuples of (node, degree).