Format/Correct/Extend docstrings and update top of modules

6 files changed, 196 insertions, 98 deletions

diff --git a/networkx/algorithms/components/attracting.py b/networkx/algorithms/components/attracting.py
index aa7971b7..9351ed00 100644
--- a/networkx/algorithms/components/attracting.py
+++ b/networkx/algorithms/components/attracting.py
@@ -1,16 +1,16 @@
 # -*- coding: utf-8 -*-
-"""
-Attracting components.
-"""
 #    Copyright (C) 2004-2016 by
 #    Aric Hagberg <hagberg@lanl.gov>
 #    Dan Schult <dschult@colgate.edu>
 #    Pieter Swart <swart@lanl.gov>
 #    All rights reserved.
 #    BSD license.
+#
+# Authors: Christopher Ellison
+"""Attracting components."""
 import networkx as nx
 from networkx.utils.decorators import not_implemented_for
-__authors__ = "\n".join(['Christopher Ellison'])
+
 __all__ = ['number_attracting_components', 
            'attracting_components',
            'is_attracting_component', 
@@ -39,6 +39,11 @@ def attracting_components(G):
     attractors : generator of sets
         A generator of sets of nodes, one for each attracting component of G.
 
+    Raises
+    ------
+    NetworkXNotImplemented :
+        If the input graph is undirected.
+
     See Also
     --------
     number_attracting_components
@@ -66,6 +71,11 @@ def number_attracting_components(G):
     n : int
         The number of attracting components in G.
 
+    Raises
+    ------
+    NetworkXNotImplemented :
+        If the input graph is undirected.
+
     See Also
     --------
     attracting_components
@@ -91,6 +101,11 @@ def is_attracting_component(G):
     attracting : bool
         True if `G` has a single attracting component. Otherwise, False.
 
+    Raises
+    ------
+    NetworkXNotImplemented :
+        If the input graph is undirected.
+
     See Also
     --------
     attracting_components
@@ -124,6 +139,11 @@ def attracting_component_subgraphs(G, copy=True):
         If copy is True, graph, node, and edge attributes are copied to the 
         subgraphs.
 
+    Raises
+    ------
+    NetworkXNotImplemented :
+        If the input graph is undirected.
+
     See Also
     --------
     attracting_components
diff --git a/networkx/algorithms/components/biconnected.py b/networkx/algorithms/components/biconnected.py
index 762e10b6..6bd6aff2 100644
--- a/networkx/algorithms/components/biconnected.py
+++ b/networkx/algorithms/components/biconnected.py
@@ -1,21 +1,19 @@
 # -*- coding: utf-8 -*-
-"""
-Biconnected components and articulation points.
-"""
-#    Copyright (C) 2011-2013 by
+#    Copyright (C) 2011-2016 by
 #    Aric Hagberg <hagberg@lanl.gov>
 #    Dan Schult <dschult@colgate.edu>
 #    Pieter Swart <swart@lanl.gov>
 #    All rights reserved.
 #    BSD license.
+#
+# Authors: Jordi Torrents (jtorrents@milnou.net)
+#          Dan Schult (dschult@colgate.edu)
+#          Aric Hagberg (aric.hagberg@gmail.com)
+"""Biconnected components and articulation points."""
 from itertools import chain
 import networkx as nx
 from networkx.utils.decorators import not_implemented_for
 
-__author__ = '\n'.join(['Jordi Torrents <jtorrents@milnou.net>',
-                        'Dan Schult <dschult@colgate.edu>',
-                        'Aric Hagberg <aric.hagberg@gmail.com>'])
-
 __all__ = [
     'biconnected_components',
     'biconnected_component_edges',
@@ -30,7 +28,7 @@ def is_biconnected(G):
     """Return True if the graph is biconnected, False otherwise.
 
     A graph is biconnected if, and only if, it cannot be disconnected by
-    removing only one node (and all edges incident on that node). If
+    removing only one node (and all edges incident on that node).  If
     removing a node increases the number of disconnected components
     in the graph, that node is called an articulation point, or cut
     vertex.  A biconnected graph has no articulation points.
@@ -65,16 +63,20 @@ def is_biconnected(G):
     articulation_points
     biconnected_component_edges
     biconnected_component_subgraphs
+    components.is_strongly_connected
+    components.is_weakly_connected
+    components.is_connected
+    components.is_semiconnected
 
     Notes
     -----
     The algorithm to find articulation points and biconnected
     components is implemented using a non-recursive depth-first-search
     (DFS) that keeps track of the highest level that back edges reach
-    in the DFS tree. A node `n` is an articulation point if, and only
+    in the DFS tree.  A node `n` is an articulation point if, and only
     if, there exists a subtree rooted at `n` such that there is no
     back edge from any successor of `n` that links to a predecessor of
-    `n` in the DFS tree. By keeping track of all the edges traversed
+    `n` in the DFS tree.  By keeping track of all the edges traversed
     by the DFS we can obtain the biconnected components because all
     edges of a bicomponent will be traversed consecutively between
     articulation points.
@@ -99,9 +101,9 @@ def biconnected_component_edges(G):
 
     Biconnected components are maximal subgraphs such that the removal of a
     node (and all edges incident on that node) will not disconnect the
-    subgraph. Note that nodes may be part of more than one biconnected
-    component. Those nodes are articulation points, or cut vertices. However,
-    each edge belongs to one, and only one, biconnected component.
+    subgraph.  Note that nodes may be part of more than one biconnected
+    component.  Those nodes are articulation points, or cut vertices.
+    However, each edge belongs to one, and only one, biconnected component.
 
     Notice that by convention a dyad is considered a biconnected component.
 
@@ -147,10 +149,10 @@ def biconnected_component_edges(G):
     The algorithm to find articulation points and biconnected
     components is implemented using a non-recursive depth-first-search
     (DFS) that keeps track of the highest level that back edges reach
-    in the DFS tree. A node `n` is an articulation point if, and only
+    in the DFS tree.  A node `n` is an articulation point if, and only
     if, there exists a subtree rooted at `n` such that there is no
     back edge from any successor of `n` that links to a predecessor of
-    `n` in the DFS tree. By keeping track of all the edges traversed
+    `n` in the DFS tree.  By keeping track of all the edges traversed
     by the DFS we can obtain the biconnected components because all
     edges of a bicomponent will be traversed consecutively between
     articulation points.
@@ -174,7 +176,7 @@ def biconnected_components(G):
     Biconnected components are maximal subgraphs such that the removal of a
     node (and all edges incident on that node) will not disconnect the
     subgraph. Note that nodes may be part of more than one biconnected
-    component. Those nodes are articulation points, or cut vertices. The
+    component.  Those nodes are articulation points, or cut vertices.  The
     removal of articulation points will increase the number of connected
     components of the graph.
 
@@ -224,9 +226,9 @@ def biconnected_components(G):
 
     See Also
     --------
-    is_biconnected,
-    articulation_points,
-    biconnected_component_edges,
+    is_biconnected
+    articulation_points
+    biconnected_component_edges
     biconnected_component_subgraphs
 
     Notes
@@ -234,10 +236,10 @@ def biconnected_components(G):
     The algorithm to find articulation points and biconnected
     components is implemented using a non-recursive depth-first-search
     (DFS) that keeps track of the highest level that back edges reach
-    in the DFS tree. A node `n` is an articulation point if, and only
+    in the DFS tree.  A node `n` is an articulation point if, and only
     if, there exists a subtree rooted at `n` such that there is no
     back edge from any successor of `n` that links to a predecessor of
-    `n` in the DFS tree. By keeping track of all the edges traversed
+    `n` in the DFS tree.  By keeping track of all the edges traversed
     by the DFS we can obtain the biconnected components because all
     edges of a bicomponent will be traversed consecutively between
     articulation points.
@@ -259,8 +261,8 @@ def biconnected_component_subgraphs(G, copy=True):
 
     Biconnected components are maximal subgraphs such that the removal of a
     node (and all edges incident on that node) will not disconnect the
-    subgraph. Note that nodes may be part of more than one biconnected
-    component. Those nodes are articulation points, or cut vertices. The
+    subgraph.  Note that nodes may be part of more than one biconnected
+    component.  Those nodes are articulation points, or cut vertices.  The
     removal of articulation points will increase the number of connected
     components of the graph.
 
@@ -312,9 +314,9 @@ def biconnected_component_subgraphs(G, copy=True):
 
     See Also
     --------
-    is_biconnected,
-    articulation_points,
-    biconnected_component_edges,
+    is_biconnected
+    articulation_points
+    biconnected_component_edges
     biconnected_components
 
     Notes
@@ -322,10 +324,10 @@ def biconnected_component_subgraphs(G, copy=True):
     The algorithm to find articulation points and biconnected
     components is implemented using a non-recursive depth-first-search
     (DFS) that keeps track of the highest level that back edges reach
-    in the DFS tree. A node `n` is an articulation point if, and only
+    in the DFS tree.  A node `n` is an articulation point if, and only
     if, there exists a subtree rooted at `n` such that there is no
     back edge from any successor of `n` that links to a predecessor of
-    `n` in the DFS tree. By keeping track of all the edges traversed
+    `n` in the DFS tree.  By keeping track of all the edges traversed
     by the DFS we can obtain the biconnected components because all
     edges of a bicomponent will be traversed consecutively between
     articulation points.
@@ -352,7 +354,7 @@ def articulation_points(G):
 
     An articulation point or cut vertex is any node whose removal (along with
     all its incident edges) increases the number of connected components of
-    a graph. An undirected connected graph without articulation points is
+    a graph.  An undirected connected graph without articulation points is
     biconnected. Articulation points belong to more than one biconnected
     component of a graph.
 
@@ -389,9 +391,9 @@ def articulation_points(G):
 
     See Also
     --------
-    is_biconnected,
-    biconnected_components,
-    biconnected_component_edges,
+    is_biconnected
+    biconnected_components
+    biconnected_component_edges
     biconnected_component_subgraphs
 
     Notes
@@ -399,10 +401,10 @@ def articulation_points(G):
     The algorithm to find articulation points and biconnected
     components is implemented using a non-recursive depth-first-search
     (DFS) that keeps track of the highest level that back edges reach
-    in the DFS tree. A node `n` is an articulation point if, and only
+    in the DFS tree.  A node `n` is an articulation point if, and only
     if, there exists a subtree rooted at `n` such that there is no
     back edge from any successor of `n` that links to a predecessor of
-    `n` in the DFS tree. By keeping track of all the edges traversed
+    `n` in the DFS tree.  By keeping track of all the edges traversed
     by the DFS we can obtain the biconnected components because all
     edges of a bicomponent will be traversed consecutively between
     articulation points.
diff --git a/networkx/algorithms/components/connected.py b/networkx/algorithms/components/connected.py
index dc17d34d..5e90da71 100644
--- a/networkx/algorithms/components/connected.py
+++ b/networkx/algorithms/components/connected.py
@@ -1,20 +1,19 @@
 # -*- coding: utf-8 -*-
-"""
-Connected components.
-"""
-#    Copyright (C) 2004-2013 by
+#    Copyright (C) 2004-2016 by
 #    Aric Hagberg <hagberg@lanl.gov>
 #    Dan Schult <dschult@colgate.edu>
 #    Pieter Swart <swart@lanl.gov>
 #    All rights reserved.
 #    BSD license.
+#
+# Authors: Eben Kenah
+#          Aric Hagberg (hagberg@lanl.gov)
+#          Christopher Ellison
+"""Connected components."""
 import networkx as nx
 from networkx.utils.decorators import not_implemented_for
 from ...utils import arbitrary_element
 
-__authors__ = "\n".join(['Eben Kenah',
-                         'Aric Hagberg <aric.hagberg@gmail.com>'
-                         'Christopher Ellison'])
 __all__ = [
     'number_connected_components',
     'connected_components',
@@ -38,6 +37,11 @@ def connected_components(G):
     comp : generator of sets
        A generator of sets of nodes, one for each component of G.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     Examples
     --------
     Generate a sorted list of connected components, largest first.
@@ -54,7 +58,8 @@ def connected_components(G):
 
     See Also
     --------
-    strongly_connected_components
+    components.strongly_connected_components
+    components.weakly_connected_components
 
     Notes
     -----
@@ -86,6 +91,11 @@ def connected_component_subgraphs(G, copy=True):
     comp : generator
       A generator of graphs, one for each connected component of G.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     Examples
     --------
     >>> G = nx.path_graph(4)
@@ -93,13 +103,15 @@ def connected_component_subgraphs(G, copy=True):
     >>> graphs = list(nx.connected_component_subgraphs(G))
 
     If you only want the largest connected component, it's more
-    efficient to use max than sort.
+    efficient to use max instead of sort:
 
     >>> Gc = max(nx.connected_component_subgraphs(G), key=len)
 
     See Also
     --------
     connected_components
+    components.strongly_connected_component_subgraphs
+    components.weakly_connected_component_subgraphs
 
     Notes
     -----
@@ -130,6 +142,8 @@ def number_connected_components(G):
     See Also
     --------
     connected_components
+    components.number_weakly_connected_components
+    components.number_strongly_connected_components
 
     Notes
     -----
@@ -153,6 +167,11 @@ def is_connected(G):
     connected : bool
       True if the graph is connected, false otherwise.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     Examples
     --------
     >>> G = nx.path_graph(4)
@@ -161,6 +180,10 @@ def is_connected(G):
 
     See Also
     --------
+    components.is_strongly_connected
+    components.is_weakly_connected
+    components.is_semiconnected
+    components.is_biconnected
     connected_components
 
     Notes
@@ -191,6 +214,11 @@ def node_connected_component(G, n):
     comp : set
        A set of nodes in the component of G containing node n.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     See Also
     --------
     connected_components
diff --git a/networkx/algorithms/components/semiconnected.py b/networkx/algorithms/components/semiconnected.py
index 07cc05dd..a9766024 100644
--- a/networkx/algorithms/components/semiconnected.py
+++ b/networkx/algorithms/components/semiconnected.py
@@ -1,18 +1,19 @@
 # -*- coding: utf-8 -*-
-"""
-Semiconnectedness.
-"""
-
-__author__ = """ysitu <ysitu@users.noreply.github.com>"""
-# Copyright (C) 2014 ysitu <ysitu@users.noreply.github.com>
-# All rights reserved.
-# BSD license.
-
+#    Copyright (C) 2004-2016 by
+#    Aric Hagberg <hagberg@lanl.gov>
+#    Dan Schult <dschult@colgate.edu>
+#    Pieter Swart <swart@lanl.gov>
+#    All rights reserved.
+#    BSD license.
+#
+# Authors: ysitu (ysitu@users.noreply.github.com)
+"""Semiconnectedness."""
 import networkx as nx
 from networkx.utils import not_implemented_for, pairwise
 
 __all__ = ['is_semiconnected']
 
+
 @not_implemented_for('undirected')
 def is_semiconnected(G):
     """Return True if the graph is semiconnected, False otherwise.
@@ -33,7 +34,7 @@ def is_semiconnected(G):
     Raises
     ------
     NetworkXNotImplemented :
-        If the input graph is not directed.
+        If the input graph is undirected.
 
     NetworkXPointlessConcept :
         If the graph is empty.
@@ -49,8 +50,10 @@ def is_semiconnected(G):
 
     See Also
     --------
-    is_strongly_connected,
-    is_weakly_connected
+    components.is_strongly_connected
+    components.is_weakly_connected
+    components.is_connected
+    components.is_biconnected
     """
     if len(G) == 0:
         raise nx.NetworkXPointlessConcept(
diff --git a/networkx/algorithms/components/strongly_connected.py b/networkx/algorithms/components/strongly_connected.py
index 98e57f5d..9fcfd1de 100644
--- a/networkx/algorithms/components/strongly_connected.py
+++ b/networkx/algorithms/components/strongly_connected.py
@@ -1,20 +1,19 @@
 # -*- coding: utf-8 -*-
-"""Strongly connected components.
-"""
 #    Copyright (C) 2004-2016 by
 #    Aric Hagberg <hagberg@lanl.gov>
 #    Dan Schult <dschult@colgate.edu>
 #    Pieter Swart <swart@lanl.gov>
 #    All rights reserved.
 #    BSD license.
+#
+# Authors: Eben Kenah
+#          Aric Hagberg (hagberg@lanl.gov)
+#          Christopher Ellison
+#          Ben Edwards (bedwards@cs.unm.edu)
+"""Strongly connected components."""
 import networkx as nx
 from networkx.utils.decorators import not_implemented_for
 
-__authors__ = "\n".join(['Eben Kenah',
-                         'Aric Hagberg (hagberg@lanl.gov)'
-                         'Christopher Ellison',
-                         'Ben Edwards (bedwards@cs.unm.edu)'])
-
 __all__ = ['number_strongly_connected_components',
            'strongly_connected_components',
            'strongly_connected_component_subgraphs',
@@ -41,7 +40,7 @@ def strongly_connected_components(G):
 
     Raises
     ------
-    NetworkXNotImplemented:
+    NetworkXNotImplemented :
         If G is undirected.
 
     Examples
@@ -61,12 +60,13 @@ def strongly_connected_components(G):
 
     See Also
     --------
-    connected_components,
-    weakly_connected_components
+    components.connected_components
+    components.weakly_connected_components
+    kosaraju_strongly_connected_components
 
     Notes
     -----
-    Uses Tarjan's algorithm with Nuutila's modifications.
+    Uses Tarjan's algorithm[1]_ with Nuutila's modifications[2]_.
     Nonrecursive version of algorithm.
 
     References
@@ -157,8 +157,7 @@ def kosaraju_strongly_connected_components(G, source=None):
 
     See Also
     --------
-    connected_components
-    weakly_connected_components
+    strongly_connected_components
 
     Notes
     -----
@@ -198,8 +197,8 @@ def strongly_connected_components_recursive(G):
 
     Raises
     ------
-    NetworkXNotImplemented:
-        If G is undirected
+    NetworkXNotImplemented :
+        If G is undirected.
 
     Examples
     --------
@@ -222,7 +221,7 @@ def strongly_connected_components_recursive(G):
 
     Notes
     -----
-    Uses Tarjan's algorithm with Nuutila's modifications.
+    Uses Tarjan's algorithm[1]_ with Nuutila's modifications[2]_.
 
     References
     ----------
@@ -284,6 +283,11 @@ def strongly_connected_component_subgraphs(G, copy=True):
     comp : generator of graphs
       A generator of graphs, one for each strongly connected component of G.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     Examples
     --------
     Generate a sorted list of strongly connected components, largest first.
@@ -301,8 +305,9 @@ def strongly_connected_component_subgraphs(G, copy=True):
 
     See Also
     --------
-    connected_component_subgraphs
-    weakly_connected_component_subgraphs
+    strongly_connected_components
+    components.connected_component_subgraphs
+    components.weakly_connected_component_subgraphs
 
     """
     for comp in strongly_connected_components(G):
@@ -326,9 +331,16 @@ def number_strongly_connected_components(G):
     n : integer
        Number of strongly connected components
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     See Also
     --------
-    connected_components
+    strongly_connected_components
+    components.number_connected_components
+    components.number_weakly_connected_components
 
     Notes
     -----
@@ -351,8 +363,17 @@ def is_strongly_connected(G):
     connected : bool
       True if the graph is strongly connected, False otherwise.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     See Also
     --------
+    components.is_weakly_connected
+    components.is_semiconnected
+    components.is_connected
+    components.is_biconnected
     strongly_connected_components
 
     Notes
@@ -386,18 +407,18 @@ def condensation(G, scc=None):
     Returns
     -------
     C : NetworkX DiGraph
-       The condensation graph C of G. The node labels are integers
+       The condensation graph C of G.  The node labels are integers
        corresponding to the index of the component in the list of
-       strongly connected components of G. C has a graph attribute named
+       strongly connected components of G.  C has a graph attribute named
        'mapping' with a dictionary mapping the original nodes to the
-       nodes in C to which they belong. Each node in C also has a node
+       nodes in C to which they belong.  Each node in C also has a node
        attribute 'members' with the set of original nodes in G that
        form the SCC that the node in C represents.
 
     Raises
     ------
     NetworkXNotImplemented:
-        If G is not directed
+        If G is undirected.
 
     Notes
     -----
diff --git a/networkx/algorithms/components/weakly_connected.py b/networkx/algorithms/components/weakly_connected.py
index 05df0166..ff2b0642 100644
--- a/networkx/algorithms/components/weakly_connected.py
+++ b/networkx/algorithms/components/weakly_connected.py
@@ -1,19 +1,17 @@
 # -*- coding: utf-8 -*-
-"""Weakly connected components.
-"""
 #    Copyright (C) 2004-2016 by
 #    Aric Hagberg <hagberg@lanl.gov>
 #    Dan Schult <dschult@colgate.edu>
 #    Pieter Swart <swart@lanl.gov>
 #    All rights reserved.
 #    BSD license.
-
+#
+# Authors: Aric Hagberg (hagberg@lanl.gov)
+#          Christopher Ellison
+"""Weakly connected components."""
 import networkx as nx
 from networkx.utils.decorators import not_implemented_for
 
-__authors__ = "\n".join(['Aric Hagberg (hagberg@lanl.gov)'
-                         'Christopher Ellison'])
-
 __all__ = [
     'number_weakly_connected_components',
     'weakly_connected_components',
@@ -37,6 +35,11 @@ def weakly_connected_components(G):
         A generator of sets of nodes, one for each weakly connected
         component of G.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     Examples
     --------
     Generate a sorted list of weakly connected components, largest first.
@@ -48,13 +51,14 @@ def weakly_connected_components(G):
     [4, 3]
 
     If you only want the largest component, it's more efficient to
-    use max instead of sort.
+    use max instead of sort:
 
     >>> largest_cc = max(nx.weakly_connected_components(G), key=len)
 
     See Also
     --------
-    strongly_connected_components
+    components.connected_components
+    components.strongly_connected_components
 
     Notes
     -----
@@ -83,9 +87,16 @@ def number_weakly_connected_components(G):
     n : integer
         Number of weakly connected components
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     See Also
     --------
-    connected_components
+    weakly_connected_components
+    components.number_connected_components
+    components.number_strongly_connected_components
 
     Notes
     -----
@@ -112,6 +123,11 @@ def weakly_connected_component_subgraphs(G, copy=True):
     comp : generator
         A generator of graphs, one for each weakly connected component of G.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     Examples
     --------
     Generate a sorted list of weakly connected components, largest first.
@@ -123,14 +139,15 @@ def weakly_connected_component_subgraphs(G, copy=True):
     [4, 3]
 
     If you only want the largest component, it's more efficient to
-    use max instead of sort.
+    use max instead of sort:
 
     >>> Gc = max(nx.weakly_connected_component_subgraphs(G), key=len)
 
     See Also
     --------
-    strongly_connected_components
-    connected_components
+    weakly_connected_components
+    components.strongly_connected_component_subgraphs
+    components.connected_component_subgraphs
 
     Notes
     -----
@@ -162,11 +179,18 @@ def is_weakly_connected(G):
     connected : bool
         True if the graph is weakly connected, False otherwise.
 
+    Raises
+    ------
+    NetworkXNotImplemented:
+        If G is undirected.
+
     See Also
     --------
-    is_strongly_connected
-    is_semiconnected
-    is_connected
+    components.is_strongly_connected
+    components.is_semiconnected
+    components.is_connected
+    components.is_biconnected
+    weakly_connected_components
 
     Notes
     -----