Merge pull request #1795 from dschult/fix-sphinx-errors

Fix some sphinx formatting errors

39 files changed, 163 insertions, 139 deletions

diff --git a/doc/source/bibliography.rst b/doc/source/bibliography.rst
index 90fde54b..3510df5d 100644
--- a/doc/source/bibliography.rst
+++ b/doc/source/bibliography.rst
@@ -5,7 +5,7 @@ Bibliography
 
 .. [BA02] R. Albert and A.-L. Barabási, "Statistical mechanics of complex
    networks", Reviews of Modern Physics, 74, pp. 47-97, 2002. 
-   :arxiv:`cond-mat/0106096`
+   http://arxiv.org/abs/cond-mat/0106096
 
 .. [Bollobas01] B. Bollobás, "Random Graphs", Second Edition,
    Cambridge University Press, 2001.
@@ -19,17 +19,17 @@ Bibliography
 
 .. [choudum1986] S.A. Choudum. "A simple proof of the Erdős-Gallai theorem on 
    graph sequences." Bulletin of the Australian Mathematical Society, 33, 
-   pp 67-70, 1986. :doi:`10.1017/S0004972700002872`
+   pp 67-70, 1986. http://dx.doi.org/10.1017/S0004972700002872
 
 .. [Diestel97] R. Diestel, "Graph Theory", Springer-Verlag, 1997. 
-   :url:`http://diestel-graph-theory.com/index.html`
+   http://diestel-graph-theory.com/index.html
 
 .. [DM03] S.N. Dorogovtsev and J.F.F. Mendes, "Evolution of Networks",
    Oxford University Press, 2003.
 
 .. [EppsteinPads] David Eppstein.
    PADS, A library of Python Algorithms and Data Structures.
-   :url:`http://www.ics.uci.edu/~eppstein/PADS`
+   http://www.ics.uci.edu/~eppstein/PADS
    
 .. [EG1960] Erdős and Gallai, Mat. Lapok 11 264, 1960.
 
@@ -48,7 +48,7 @@ Bibliography
 
 .. [Newman03] M.E.J. Newman, "The Structure and Function of Complex
    Networks", SIAM Review, 45, pp. 167-256, 2003. 
-   :url:`http://epubs.siam.org/doi/abs/10.1137/S003614450342480`
+   http://epubs.siam.org/doi/abs/10.1137/S003614450342480
 
 .. [Sedgewick02] R. Sedgewick, "Algorithms in C: Parts 1-4: 
    Fundamentals, Data Structure, Sorting, Searching", Addison Wesley
@@ -61,5 +61,5 @@ Bibliography
     2nd ed., 2001.
 
 .. [vanRossum98] Guido van Rossum. Python Patterns - Implementing Graphs, 1998.
-   :url:`http://www.python.org/doc/essays/graphs`
+   http://www.python.org/doc/essays/graphs
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
index e265348d..96ea8ef4 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -55,7 +55,7 @@ if on_rtd:
         # from networkx/doc/source (which holds conf.py).
         py = sys.executable
         subprocess.call([py, 'make_gallery.py'])
-        subprocess.call([py, 'make_examples.py', '../examples', 'source'])
+        subprocess.call([py, 'make_examples_rst.py', '../examples', 'source'])
 
 # If your extensions are in another directory, add it here.
 # These locations are relative to conf.py
diff --git a/doc/source/install.rst b/doc/source/install.rst
index ead919e7..ff6983ae 100644
--- a/doc/source/install.rst
+++ b/doc/source/install.rst
@@ -74,11 +74,11 @@ GitHub
 ------
 
   1. Clone the networkx repostitory
-    ::
+     (see https://github.com/networkx/networkx/ for options)
+     ::
 
        git clone https://github.com/networkx/networkx.git
 
-  (see https://github.com/networkx/networkx/ for other options)
 
   2. Change directory to :samp:`networkx`
 
diff --git a/doc/source/reference/algorithms.rst b/doc/source/reference/algorithms.rst
index 88c1e32d..22d2fdb0 100644
--- a/doc/source/reference/algorithms.rst
+++ b/doc/source/reference/algorithms.rst
@@ -41,7 +41,6 @@ Algorithms
    algorithms.matching
    algorithms.minors
    algorithms.mis
-   algorithms.mst
    algorithms.operators
    algorithms.rich_club
    algorithms.shortest_paths
diff --git a/doc/source/reference/api_1.5.rst b/doc/source/reference/api_1.5.rst
index 04d5b121..ff71226d 100644
--- a/doc/source/reference/api_1.5.rst
+++ b/doc/source/reference/api_1.5.rst
@@ -12,7 +12,7 @@ Weighted graph algorithms
 
 Many 'weighted' graph algorithms now take optional parameter to 
 specifiy which edge attribute should be used for the weight
-(default='weight') (:ticket:`509`)
+(default='weight') (ticket https://networkx.lanl.gov/trac/ticket/509)
 
 In some cases the parameter name was changed from weighted_edges,
 or weighted, to weight.  Here is how to specify which edge attribute 
diff --git a/doc/source/reference/api_1.6.rst b/doc/source/reference/api_1.6.rst
index f3d6944c..d2a130c3 100644
--- a/doc/source/reference/api_1.6.rst
+++ b/doc/source/reference/api_1.6.rst
@@ -21,7 +21,7 @@ Weighted graph algorithms
 
 Many 'weighted' graph algorithms now take optional parameter to 
 specifiy which edge attribute should be used for the weight
-(default='weight') (:ticket:`573`)
+(default='weight') (ticket https://networkx.lanl.gov/trac/ticket/573)
 
 In some cases the parameter name was changed from weighted, to weight.  Here is
 how to specify which edge attribute will be used in the algorithms:
diff --git a/doc/source/reference/classes.digraph.rst b/doc/source/reference/classes.digraph.rst
index 278386f1..c056829f 100644
--- a/doc/source/reference/classes.digraph.rst
+++ b/doc/source/reference/classes.digraph.rst
@@ -9,6 +9,9 @@ Overview
 .. currentmodule:: networkx
 .. autofunction:: DiGraph
 
+=======
+Methods
+=======
 
 Adding and removing nodes and edges
 ===================================
diff --git a/doc/source/reference/classes.graph.rst b/doc/source/reference/classes.graph.rst
index 12244c78..f82c8fa5 100644
--- a/doc/source/reference/classes.graph.rst
+++ b/doc/source/reference/classes.graph.rst
@@ -9,6 +9,10 @@ Overview
 .. currentmodule:: networkx
 .. autofunction:: Graph
 
+=======
+Methods
+=======
+
 Adding and removing nodes and edges
 ===================================
 
diff --git a/doc/source/reference/classes.multidigraph.rst b/doc/source/reference/classes.multidigraph.rst
index feb33a06..a2f6a057 100644
--- a/doc/source/reference/classes.multidigraph.rst
+++ b/doc/source/reference/classes.multidigraph.rst
@@ -10,6 +10,10 @@ Overview
 .. currentmodule:: networkx
 .. autofunction:: MultiDiGraph
 
+=======
+Methods
+=======
+
 Adding and Removing Nodes and Edges
 ===================================
 
diff --git a/doc/source/reference/classes.multigraph.rst b/doc/source/reference/classes.multigraph.rst
index c27f0153..d73de069 100644
--- a/doc/source/reference/classes.multigraph.rst
+++ b/doc/source/reference/classes.multigraph.rst
@@ -9,6 +9,10 @@ Overview
 .. currentmodule:: networkx
 .. autofunction:: MultiGraph
 
+=======
+Methods
+=======
+
 Adding and removing nodes and edges
 ===================================
 
diff --git a/doc/source/reference/functions.rst b/doc/source/reference/functions.rst
index 69465cb4..0679a88c 100644
--- a/doc/source/reference/functions.rst
+++ b/doc/source/reference/functions.rst
@@ -24,7 +24,6 @@ Nodes
 
    nodes
    number_of_nodes
-   nodes_iter
    all_neighbors
    non_neighbors
    common_neighbors
@@ -38,7 +37,6 @@ Edges
 
    edges
    number_of_edges
-   edges_iter
    non_edges
 
 
diff --git a/doc/source/reference/news.rst b/doc/source/reference/news.rst
index 7ffd8303..cd935d67 100644
--- a/doc/source/reference/news.rst
+++ b/doc/source/reference/news.rst
@@ -8,6 +8,10 @@ NetworkX 2.0
 ------------
 Release date: TBD
 
+.. toctree::
+
+   migration_guide_from_1.x_to_2.0
+
 NetworkX 1.10
 --------------
 Release date: 2 August 2015
@@ -18,11 +22,13 @@ Highlights
 ~~~~~~~~~~
 - Connected components now return generators
 - new functions including
-  - enumerate_all_cliques, greedy_coloring, edge_dfs, find_cycle
+
+  + enumerate_all_cliques, greedy_coloring, edge_dfs, find_cycle
     immediate_dominators, harmonic_centrality
-  - Hopcraft--Karp algorithm for maximum matchings
-  - optimum branchings and arborescences.
-  - all_simple_paths
+  + Hopcraft--Karp algorithm for maximum matchings
+  + optimum branchings and arborescences.
+  + all_simple_paths
+
 - pyparsing dependence removed from GML reader/parser
 - improve flow algorithms
 - new generators releated to expander graphs.
@@ -188,7 +194,8 @@ New features
    that handle subsets of nodes
  - :mod:`In-place node relabeling <networkx.relabel>` 
  - Many 'weighted' graph algorithms now take optional parameter to use 
-   specified edge attribute (default='weight') (:ticket:`509`)
+   specified edge attribute (default='weight')
+   (ticket https://networkx.lanl.gov/trac/ticket/509)
 
  - Test for :mod:`distance regular <networkx.algorithms.distance_regular>` graphs
  - Fast :mod:`directed Erdős-Renyi graph  <networkx.generators.random_graphs>` generator
@@ -206,21 +213,34 @@ See :doc:`api_1.5`
 
 Bug fixes
 ~~~~~~~~~
- - Fix edge handling for multigraphs in networkx/graphviz interface 
-   (:ticket:`507`)
- - Update networkx/pydot interface for new versions of pydot 
-   (:ticket:`506`), (:ticket:`535`)
- - Fix negative cycle handling in Bellman-Ford (:ticket:`502`)
- - Write more attributes with GraphML and GML formats (:ticket:`480`)
- - Handle white space better in read_edgelist (:ticket:`513`)
- - Better parsing of Pajek format files (:ticket:`524`) (:ticket:`542`)
- - Isolates functions work with directed graphs (:ticket:`526`)
- - Faster conversion to numpy matrices (:ticket:`529`)
- - Add graph['name'] and use properties to access Graph.name (:ticket:`544`)
- - Topological sort confused None and 0 (:ticket:`546`)
- - GEXF writer mishandled weight=0 (:ticket:`550`)
- - Speedup in SciPy version of PageRank (:ticket:`554`)
- - Numpy PageRank node order incorrect + speedups (:ticket:`555`)
+ - Fix edge handling for multigraphs in networkx/graphviz interface
+   (ticket https://networkx.lanl.gov/trac/ticket/507)
+ - Update networkx/pydot interface for new versions of pydot
+   (ticket https://networkx.lanl.gov/trac/ticket/506)
+   (ticket https://networkx.lanl.gov/trac/ticket/535)
+ - Fix negative cycle handling in Bellman-Ford
+   (ticket https://networkx.lanl.gov/trac/ticket/502)
+ - Write more attributes with GraphML and GML formats
+   (ticket https://networkx.lanl.gov/trac/ticket/480)
+ - Handle white space better in read_edgelist
+   (ticket https://networkx.lanl.gov/trac/ticket/513)
+ - Better parsing of Pajek format files
+   (ticket https://networkx.lanl.gov/trac/ticket/524)
+   (ticket https://networkx.lanl.gov/trac/ticket/542)
+ - Isolates functions work with directed graphs
+   (ticket https://networkx.lanl.gov/trac/ticket/526)
+ - Faster conversion to numpy matrices
+   (ticket https://networkx.lanl.gov/trac/ticket/529)
+ - Add graph['name'] and use properties to access Graph.name
+   (ticket https://networkx.lanl.gov/trac/ticket/544)
+ - Topological sort confused None and 0
+   (ticket https://networkx.lanl.gov/trac/ticket/546)
+ - GEXF writer mishandled weight=0
+   (ticket https://networkx.lanl.gov/trac/ticket/550)
+ - Speedup in SciPy version of PageRank
+   (ticket https://networkx.lanl.gov/trac/ticket/554)
+ - Numpy PageRank node order incorrect + speedups
+   (ticket https://networkx.lanl.gov/trac/ticket/555)
 
 NetworkX 1.4
 ------------
diff --git a/doc/source/reference/release_2.0.rst b/doc/source/reference/release_2.0.rst
index 77f1284e..f511f4f5 100644
--- a/doc/source/reference/release_2.0.rst
+++ b/doc/source/reference/release_2.0.rst
@@ -11,7 +11,7 @@ Please send comments and questions to the networkx-discuss [mailing list](http:/
 
 API changes
 -----------
-* [`<>`_]
+* Base Graph Class Changes
   With the release of NetworkX 2.0 we are moving towards an iterator reporting API.
   We used to have two methods for the same property of the graph, one that returns a
   list and one that returns an iterator. With 2.0 we have removed the one that returns
diff --git a/networkx/algorithms/assortativity/connectivity.py b/networkx/algorithms/assortativity/connectivity.py
index 67eb4871..d29dc880 100644
--- a/networkx/algorithms/assortativity/connectivity.py
+++ b/networkx/algorithms/assortativity/connectivity.py
@@ -48,18 +48,17 @@ def _avg_deg_conn(G, neighbors, source_degree, target_degree,
 
 def average_degree_connectivity(G, source="in+out", target="in+out",
                                 nodes=None, weight=None):
-    """Compute the average degree connectivity of graph.
+    r"""Compute the average degree connectivity of graph.
 
     The average degree connectivity is the average nearest neighbor degree of
     nodes with degree k. For weighted graphs, an analogous measure can
     be computed using the weighted average neighbors degree defined in
-    [1]_, for a node `i`, as:
+    [1]_, for a node `i`, as
 
     .. math::
 
         k_{nn,i}^{w} = \frac{1}{s_i} \sum_{j \in N(i)} w_{ij} k_j
 
-
     where `s_i` is the weighted degree of node `i`,
     `w_{ij}` is the weight of the edge that links `i` and `j`,
     and `N(i)` are the neighbors of node `i`.
@@ -74,7 +73,7 @@ def average_degree_connectivity(G, source="in+out", target="in+out",
     target : "in"|"out"|"in+out" (default:"in+out"
        Directed graphs only. Use "in"- or "out"-degree for target node.
 
-    nodes: list or iterable (optional)
+    nodes : list or iterable (optional)
         Compute neighbor connectivity for these nodes. The default is all
         nodes.
 
@@ -84,7 +83,7 @@ def average_degree_connectivity(G, source="in+out", target="in+out",
 
     Returns
     -------
-    d: dict
+    d : dict
        A dictionary keyed by degree k with the value of average connectivity.
 
     Examples
diff --git a/networkx/algorithms/bipartite/projection.py b/networkx/algorithms/bipartite/projection.py
index ea401cfa..46540248 100644
--- a/networkx/algorithms/bipartite/projection.py
+++ b/networkx/algorithms/bipartite/projection.py
@@ -63,7 +63,7 @@ def projected_graph(B, nodes, multigraph=False):
     [['a', 'b'], ['a', 'b']]
 
     Notes
-    ------
+    -----
     No attempt is made to verify that the input graph B is bipartite.
     Returns a simple graph that is the projection of the bipartite graph B
     onto the set of nodes given in list nodes.  If multigraph=True then
@@ -158,7 +158,7 @@ def weighted_projected_graph(B, nodes, ratio=False):
     [(1, 3, {'weight': 0.5})]
     
     Notes
-    ------
+    -----
     No attempt is made to verify that the input graph B is bipartite.
     The graph and node properties are (shallow) copied to the projected graph.
 
@@ -252,7 +252,7 @@ def collaboration_weighted_projected_graph(B, nodes):
     (2, 5, {'weight': 0.5})
     
     Notes
-    ------
+    -----
     No attempt is made to verify that the input graph B is bipartite.
     The graph and node properties are (shallow) copied to the projected graph.
 
@@ -344,7 +344,7 @@ def overlap_weighted_projected_graph(B, nodes, jaccard=True):
     [(0, 2, {'weight': 1.0}), (2, 4, {'weight': 1.0})]
     
     Notes
-    ------
+    -----
     No attempt is made to verify that the input graph B is bipartite.
     The graph and node properties are (shallow) copied to the projected graph.
 
@@ -457,7 +457,7 @@ def generic_weighted_projected_graph(B, nodes, weight_function=None):
     [(0, 1, {'weight': 10})]
     
     Notes
-    ------
+    -----
     No attempt is made to verify that the input graph B is bipartite.
     The graph and node properties are (shallow) copied to the projected graph.
 
diff --git a/networkx/algorithms/centrality/betweenness.py b/networkx/algorithms/centrality/betweenness.py
index 8fcdaf4a..b8c2b125 100644
--- a/networkx/algorithms/centrality/betweenness.py
+++ b/networkx/algorithms/centrality/betweenness.py
@@ -25,7 +25,7 @@ def betweenness_centrality(G, k=None, normalized=True, weight=None,
     r"""Compute the shortest-path betweenness centrality for nodes.
 
     Betweenness centrality of a node `v` is the sum of the
-    fraction of all-pairs shortest paths that pass through `v`:
+    fraction of all-pairs shortest paths that pass through `v`
 
     .. math::
 
@@ -134,7 +134,7 @@ def edge_betweenness_centrality(G, k=None, normalized=True, weight=None,
     r"""Compute betweenness centrality for edges.
 
     Betweenness centrality of an edge `e` is the sum of the
-    fraction of all-pairs shortest paths that pass through `e`:
+    fraction of all-pairs shortest paths that pass through `e`
 
     .. math::
 
diff --git a/networkx/algorithms/centrality/betweenness_subset.py b/networkx/algorithms/centrality/betweenness_subset.py
index 6b3f497b..8797f791 100644
--- a/networkx/algorithms/centrality/betweenness_subset.py
+++ b/networkx/algorithms/centrality/betweenness_subset.py
@@ -24,7 +24,7 @@ from networkx.algorithms.centrality.betweenness import\
 def betweenness_centrality_subset(G,sources,targets,
                                   normalized=False,
                                   weight=None):
-    """Compute betweenness centrality for a subset of nodes.
+    r"""Compute betweenness centrality for a subset of nodes.
 
     .. math::
 
@@ -106,7 +106,7 @@ def betweenness_centrality_subset(G,sources,targets,
 def edge_betweenness_centrality_subset(G,sources,targets,
                                        normalized=False,
                                        weight=None):
-    """Compute betweenness centrality for edges for a subset of nodes.
+    r"""Compute betweenness centrality for edges for a subset of nodes.
 
     .. math::
 
diff --git a/networkx/algorithms/centrality/eigenvector.py b/networkx/algorithms/centrality/eigenvector.py
index 508d5352..7e9e771d 100644
--- a/networkx/algorithms/centrality/eigenvector.py
+++ b/networkx/algorithms/centrality/eigenvector.py
@@ -68,7 +68,7 @@ def eigenvector_centrality(G, max_iter=100, tol=1.0e-6, nstart=None,
     hits
 
     Notes
-    ------
+    -----
     The measure was introduced by [1]_ and is discussed in [2]_.
 
     Eigenvector convergence: The power iteration method is used to compute
@@ -179,7 +179,7 @@ def eigenvector_centrality_numpy(G, weight='weight'):
     hits
 
     Notes
-    ------
+    -----
     The measure was introduced by [1]_.
 
     This algorithm uses the SciPy sparse eigenvalue solver (ARPACK) to
diff --git a/networkx/algorithms/centrality/harmonic.py b/networkx/algorithms/centrality/harmonic.py
index 62ba653b..8cb374ec 100644
--- a/networkx/algorithms/centrality/harmonic.py
+++ b/networkx/algorithms/centrality/harmonic.py
@@ -13,14 +13,14 @@ __all__ = ['harmonic_centrality']
 
 
 def harmonic_centrality(G, distance=None):
-    """Compute harmonic centrality for nodes.
+    r"""Compute harmonic centrality for nodes.
 
     Harmonic centrality [1]_ of a node `u` is the sum of the reciprocal
-    of the shortest path distances from all other nodes to `u`.
+    of the shortest path distances from all other nodes to `u`
 
     .. math::
 
-        C(u) = \sum_{v \neq u \epsilon G} \frac{1}{d(v, u)},
+        C(u) = \sum_{v \neq u} \frac{1}{d(v, u)}
 
     where `d(v, u)` is the shortest-path distance between `v` and `u`.
 
@@ -30,6 +30,7 @@ def harmonic_centrality(G, distance=None):
     ----------
     G : graph
       A NetworkX graph
+
     distance : edge attribute key, optional (default=None)
       Use the specified edge attribute as the edge distance in shortest
       path calculations.  If `None`, then each edge will have distance equal to 1.
diff --git a/networkx/algorithms/centrality/katz.py b/networkx/algorithms/centrality/katz.py
index e5742f6c..19eabeb2 100644
--- a/networkx/algorithms/centrality/katz.py
+++ b/networkx/algorithms/centrality/katz.py
@@ -280,7 +280,7 @@ def katz_centrality_numpy(G, alpha=0.1, beta=1.0, normalized=True,
     hits
 
     Notes
-    ------
+    -----
     Katz centrality was introduced by [2]_.
 
     This algorithm uses a direct linear solver to solve the above equation.
diff --git a/networkx/algorithms/clique.py b/networkx/algorithms/clique.py
index 265fe50f..b69b1f81 100644
--- a/networkx/algorithms/clique.py
+++ b/networkx/algorithms/clique.py
@@ -8,9 +8,9 @@
 
 Finding the largest clique in a graph is NP-complete problem, so most of
 these algorithms have an exponential running time; for more information,
-see the Wikipedia article on the `clique problem`_.
+see the Wikipedia article on the clique problem [1]_.
 
-.. _clique problem:: https://en.wikipedia.org/wiki/Clique_problem
+.. [1] clique problem:: https://en.wikipedia.org/wiki/Clique_problem
 
 """
 from collections import deque
diff --git a/networkx/algorithms/flow/__init__.py b/networkx/algorithms/flow/__init__.py
index 5ce83109..cadfafb4 100644
--- a/networkx/algorithms/flow/__init__.py
+++ b/networkx/algorithms/flow/__init__.py
@@ -1,17 +1,3 @@
-# this import is used to combine the __all__ varibles.
-from . import (maxflow, mincost, edmondskarp, preflowpush,
-        shortestaugmentingpath, capacityscaling, networksimplex)
-
-__all__ = sum([maxflow.__all__,
-                mincost.__all__,
-                edmondskarp.__all__,
-                preflowpush.__all__,
-                shortestaugmentingpath.__all__,
-                capacityscaling.__all__,
-                networksimplex.__all__,
-                ['build_flow_dict', 'build_residual_network']
-            ], [])
-
 from .maxflow import *
 from .mincost import *
 from .edmondskarp import *
diff --git a/networkx/algorithms/flow/capacityscaling.py b/networkx/algorithms/flow/capacityscaling.py
index 7d6152b6..1a425075 100644
--- a/networkx/algorithms/flow/capacityscaling.py
+++ b/networkx/algorithms/flow/capacityscaling.py
@@ -130,7 +130,7 @@ def _build_flow_dict(G, R, capacity, weight):
 
 def capacity_scaling(G, demand='demand', capacity='capacity', weight='weight',
                      heap=BinaryHeap):
-    """Find a minimum cost flow satisfying all demands in digraph G.
+    r"""Find a minimum cost flow satisfying all demands in digraph G.
 
     This is a capacity scaling successive shortest augmenting path algorithm.
 
@@ -180,16 +180,14 @@ def capacity_scaling(G, demand='demand', capacity='capacity', weight='weight',
 
     Returns
     -------
-    flowCost: integer
+    flowCost : integer
         Cost of a minimum cost flow satisfying all demands.
 
-    flowDict: dictionary
-        Dictionary of dictionaries keyed by nodes such that
-        flowDict[u][v] is the flow edge (u, v) if G is a digraph.
-
-        Dictionary of dictionaries of dictionaries keyed by nodes such that
-        flowDict[u][v][key] is the flow edge (u, v, key) if G is a
-        multidigraph.
+    flowDict : dictionary
+        If G is a digraph, a dict-of-dicts keyed by nodes such that
+        flowDict[u][v] is the flow on edge (u, v).
+        If G is a MultiDiGraph, a dict-of-dicts-of-dicts keyed by nodes
+        so that flowDict[u][v][key] is the flow on edge (u, v, key).
 
     Raises
     ------
@@ -199,6 +197,7 @@ def capacity_scaling(G, demand='demand', capacity='capacity', weight='weight',
 
     NetworkXUnfeasible
         This exception is raised in the following situations:
+
             * The sum of the demands is not zero. Then, there is no
               flow satisfying all demands.
             * There is no flow satisfying all demand.
diff --git a/networkx/algorithms/flow/mincost.py b/networkx/algorithms/flow/mincost.py
index adaeb2ac..2b3b5566 100644
--- a/networkx/algorithms/flow/mincost.py
+++ b/networkx/algorithms/flow/mincost.py
@@ -19,7 +19,7 @@ import networkx as nx
 
 def min_cost_flow_cost(G, demand = 'demand', capacity = 'capacity',
                         weight = 'weight'):
-    """Find the cost of a minimum cost flow satisfying all demands in digraph G.
+    r"""Find the cost of a minimum cost flow satisfying all demands in digraph G.
 
     G is a digraph with edge costs and capacities and in which nodes
     have demand, i.e., they want to send or receive some amount of
@@ -34,7 +34,7 @@ def min_cost_flow_cost(G, demand = 'demand', capacity = 'capacity',
         DiGraph on which a minimum cost flow satisfying all demands is
         to be found.
 
-    demand: string
+    demand : string
         Nodes of the graph G are expected to have an attribute demand
         that indicates how much flow a node wants to send (negative
         demand) or receive (positive demand). Note that the sum of the
@@ -42,13 +42,13 @@ def min_cost_flow_cost(G, demand = 'demand', capacity = 'capacity',
         this attribute is not present, a node is considered to have 0
         demand. Default value: 'demand'.
 
-    capacity: string
+    capacity : string
         Edges of the graph G are expected to have an attribute capacity
         that indicates how much flow the edge can support. If this
         attribute is not present, the edge is considered to have
         infinite capacity. Default value: 'capacity'.
 
-    weight: string
+    weight : string
         Edges of the graph G are expected to have an attribute weight
         that indicates the cost incurred by sending one unit of flow on
         that edge. If not present, the weight is considered to be 0.
@@ -56,7 +56,7 @@ def min_cost_flow_cost(G, demand = 'demand', capacity = 'capacity',
 
     Returns
     -------
-    flowCost: integer, float
+    flowCost : integer, float
         Cost of a minimum cost flow satisfying all demands.
 
     Raises
@@ -67,6 +67,7 @@ def min_cost_flow_cost(G, demand = 'demand', capacity = 'capacity',
 
     NetworkXUnfeasible
         This exception is raised in the following situations:
+
             * The sum of the demands is not zero. Then, there is no
               flow satisfying all demands.
             * There is no flow satisfying all demand.
@@ -102,7 +103,7 @@ def min_cost_flow_cost(G, demand = 'demand', capacity = 'capacity',
 
 def min_cost_flow(G, demand = 'demand', capacity = 'capacity',
                   weight = 'weight'):
-    """Return a minimum cost flow satisfying all demands in digraph G.
+    r"""Return a minimum cost flow satisfying all demands in digraph G.
 
     G is a digraph with edge costs and capacities and in which nodes
     have demand, i.e., they want to send or receive some amount of
@@ -117,7 +118,7 @@ def min_cost_flow(G, demand = 'demand', capacity = 'capacity',
         DiGraph on which a minimum cost flow satisfying all demands is
         to be found.
 
-    demand: string
+    demand : string
         Nodes of the graph G are expected to have an attribute demand
         that indicates how much flow a node wants to send (negative
         demand) or receive (positive demand). Note that the sum of the
@@ -125,13 +126,13 @@ def min_cost_flow(G, demand = 'demand', capacity = 'capacity',
         this attribute is not present, a node is considered to have 0
         demand. Default value: 'demand'.
 
-    capacity: string
+    capacity : string
         Edges of the graph G are expected to have an attribute capacity
         that indicates how much flow the edge can support. If this
         attribute is not present, the edge is considered to have
         infinite capacity. Default value: 'capacity'.
 
-    weight: string
+    weight : string
         Edges of the graph G are expected to have an attribute weight
         that indicates the cost incurred by sending one unit of flow on
         that edge. If not present, the weight is considered to be 0.
@@ -139,7 +140,7 @@ def min_cost_flow(G, demand = 'demand', capacity = 'capacity',
 
     Returns
     -------
-    flowDict: dictionary
+    flowDict : dictionary
         Dictionary of dictionaries keyed by nodes such that
         flowDict[u][v] is the flow edge (u, v).
 
@@ -151,6 +152,7 @@ def min_cost_flow(G, demand = 'demand', capacity = 'capacity',
 
     NetworkXUnfeasible
         This exception is raised in the following situations:
+
             * The sum of the demands is not zero. Then, there is no
               flow satisfying all demands.
             * There is no flow satisfying all demand.
@@ -195,19 +197,19 @@ def cost_of_flow(G, flowDict, weight = 'weight'):
         DiGraph on which a minimum cost flow satisfying all demands is
         to be found.
 
-    weight: string
+    weight : string
         Edges of the graph G are expected to have an attribute weight
         that indicates the cost incurred by sending one unit of flow on
         that edge. If not present, the weight is considered to be 0.
         Default value: 'weight'.
 
-    flowDict: dictionary
+    flowDict : dictionary
         Dictionary of dictionaries keyed by nodes such that
         flowDict[u][v] is the flow edge (u, v).
 
     Returns
     -------
-    cost: Integer, float
+    cost : Integer, float
         The total cost of the flow. This is given by the sum over all
         edges of the product of the edge's flow and the edge's weight.
 
diff --git a/networkx/algorithms/flow/networksimplex.py b/networkx/algorithms/flow/networksimplex.py
index 3d4c5edb..c1d75275 100644
--- a/networkx/algorithms/flow/networksimplex.py
+++ b/networkx/algorithms/flow/networksimplex.py
@@ -27,7 +27,7 @@ except NameError:
 
 @not_implemented_for('undirected')
 def network_simplex(G, demand='demand', capacity='capacity', weight='weight'):
-    """Find a minimum cost flow satisfying all demands in digraph G.
+    r"""Find a minimum cost flow satisfying all demands in digraph G.
 
     This is a primal network simplex algorithm that uses the leaving
     arc rule to prevent cycling.
@@ -45,7 +45,7 @@ def network_simplex(G, demand='demand', capacity='capacity', weight='weight'):
         DiGraph on which a minimum cost flow satisfying all demands is
         to be found.
 
-    demand: string
+    demand : string
         Nodes of the graph G are expected to have an attribute demand
         that indicates how much flow a node wants to send (negative
         demand) or receive (positive demand). Note that the sum of the
@@ -53,13 +53,13 @@ def network_simplex(G, demand='demand', capacity='capacity', weight='weight'):
         this attribute is not present, a node is considered to have 0
         demand. Default value: 'demand'.
 
-    capacity: string
+    capacity : string
         Edges of the graph G are expected to have an attribute capacity
         that indicates how much flow the edge can support. If this
         attribute is not present, the edge is considered to have
         infinite capacity. Default value: 'capacity'.
 
-    weight: string
+    weight : string
         Edges of the graph G are expected to have an attribute weight
         that indicates the cost incurred by sending one unit of flow on
         that edge. If not present, the weight is considered to be 0.
@@ -67,10 +67,10 @@ def network_simplex(G, demand='demand', capacity='capacity', weight='weight'):
 
     Returns
     -------
-    flowCost: integer, float
+    flowCost : integer, float
         Cost of a minimum cost flow satisfying all demands.
 
-    flowDict: dictionary
+    flowDict : dictionary
         Dictionary of dictionaries keyed by nodes such that
         flowDict[u][v] is the flow edge (u, v).
 
@@ -82,6 +82,7 @@ def network_simplex(G, demand='demand', capacity='capacity', weight='weight'):
 
     NetworkXUnfeasible
         This exception is raised in the following situations:
+
             * The sum of the demands is not zero. Then, there is no
               flow satisfying all demands.
             * There is no flow satisfying all demand.
diff --git a/networkx/algorithms/link_analysis/hits_alg.py b/networkx/algorithms/link_analysis/hits_alg.py
index 896e1981..7325352c 100644
--- a/networkx/algorithms/link_analysis/hits_alg.py
+++ b/networkx/algorithms/link_analysis/hits_alg.py
@@ -137,7 +137,7 @@ def hits_numpy(G,normalized=True):
     Hubs estimates the node value based on outgoing links.
 
     Parameters
-    -----------
+    ----------
     G : graph
       A NetworkX graph
 
@@ -207,7 +207,7 @@ def hits_scipy(G,max_iter=100,tol=1.0e-6,normalized=True):
     Hubs estimates the node value based on outgoing links.
 
     Parameters
-    -----------
+    ----------
     G : graph
       A NetworkX graph
 
diff --git a/networkx/algorithms/matching.py b/networkx/algorithms/matching.py
index 6d2c4f58..ca546c9f 100644
--- a/networkx/algorithms/matching.py
+++ b/networkx/algorithms/matching.py
@@ -83,7 +83,7 @@ def max_weight_matching(G, maxcardinality=False, weight='weight'):
 
 
     Notes
-    ------
+    -----
     If G has edges with weight attributes the edge data are used as
     weight values else the weights are assumed to be 1.
 
diff --git a/networkx/algorithms/mis.py b/networkx/algorithms/mis.py
index 290dad6c..4b6aab9b 100644
--- a/networkx/algorithms/mis.py
+++ b/networkx/algorithms/mis.py
@@ -56,7 +56,7 @@ def maximal_independent_set(G, nodes=None):
     [1, 3]
     
     Notes
-    ------
+    -----
     This algorithm does not solve the maximum independent set problem.
 
     """
diff --git a/networkx/algorithms/richclub.py b/networkx/algorithms/richclub.py
index bbd4bd63..b47eeb4f 100644
--- a/networkx/algorithms/richclub.py
+++ b/networkx/algorithms/richclub.py
@@ -42,7 +42,7 @@ def rich_club_coefficient(G, normalized=True, Q=100):
     0.4
 
     Notes
-    ------
+    -----
     The rich club definition and algorithm are found in [1]_.  This
     algorithm ignores any edge weights and is not defined for directed
     graphs or graphs with parallel edges or self loops.
diff --git a/networkx/algorithms/shortest_paths/weighted.py b/networkx/algorithms/shortest_paths/weighted.py
index dceb816f..10254858 100644
--- a/networkx/algorithms/shortest_paths/weighted.py
+++ b/networkx/algorithms/shortest_paths/weighted.py
@@ -66,7 +66,7 @@ def dijkstra_path(G, source, target, weight='weight'):
     [0, 1, 2, 3, 4]
 
     Notes
-    ------
+    -----
     Edge weight attributes must be numerical.
     Distances are calculated as sums of weighted edges traversed.
 
@@ -266,7 +266,7 @@ def single_source_dijkstra(G, source, target=None, cutoff=None, weight='weight')
     [0, 1, 2, 3, 4]
 
     Notes
-    ---------
+    -----
     Edge weight attributes must be numerical.
     Distances are calculated as sums of weighted edges traversed.
 
@@ -1050,7 +1050,7 @@ def johnson(G, weight='weight'):
     ['0', '1', '2']
 
     Notes
-    ------
+    -----
     Johnson's algorithm is suitable even for graphs with negative weights. It
     works by using the Bellman–Ford algorithm to compute a transformation of
     the input graph that removes all negative weights, allowing Dijkstra's
diff --git a/networkx/classes/digraph.py b/networkx/classes/digraph.py
index 7822edc5..5777af74 100644
--- a/networkx/classes/digraph.py
+++ b/networkx/classes/digraph.py
@@ -37,6 +37,7 @@ class DiGraph(Graph):
         NetworkX graph object.  If the corresponding optional Python
         packages are installed the data can also be a NumPy matrix
         or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
+
     attr : keyword arguments, optional (default= no attributes)
         Attributes to add to graph as key=value pairs.
 
@@ -518,7 +519,7 @@ class DiGraph(Graph):
 
         Parameters
         ----------
-        u,v : nodes
+        u, v : nodes
             Nodes can be, for example, strings or numbers.
             Nodes must be hashable (and not None) Python objects.
         attr_dict : dictionary, optional (default= no attributes)
@@ -663,7 +664,7 @@ class DiGraph(Graph):
 
         Parameters
         ----------
-        u,v: nodes
+        u, v : nodes
             Remove the edge between nodes u and v.
 
         Raises
diff --git a/networkx/classes/function.py b/networkx/classes/function.py
index 64016b7c..1806bfbf 100644
--- a/networkx/classes/function.py
+++ b/networkx/classes/function.py
@@ -142,7 +142,7 @@ def freeze(G):
     Node and edge data can still be modified.
 
     Parameters
-    -----------
+    ----------
     G : graph
       A NetworkX graph
 
@@ -188,7 +188,7 @@ def is_frozen(G):
     """Return True if graph is frozen.
 
     Parameters
-    -----------
+    ----------
     G : graph
       A NetworkX graph
 
diff --git a/networkx/classes/graph.py b/networkx/classes/graph.py
index b6254be7..7ea3b91c 100644
--- a/networkx/classes/graph.py
+++ b/networkx/classes/graph.py
@@ -46,6 +46,7 @@ class Graph(object):
         NetworkX graph object.  If the corresponding optional Python
         packages are installed the data can also be a NumPy matrix
         or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
+
     attr : keyword arguments, optional (default= no attributes)
         Attributes to add to graph as key=value pairs.
 
@@ -640,7 +641,6 @@ class Graph(object):
         [0, 1, 2]
 
         To get the node data along with the nodes::
-
         >>> G.add_node(1, time='5pm')
         >>> G.node[0]['foo'] = 'bar'
         >>> list(G.nodes(data=True))
@@ -723,7 +723,7 @@ class Graph(object):
 
         Parameters
         ----------
-        u,v : nodes
+        u, v : nodes
             Nodes can be, for example, strings or numbers.
             Nodes must be hashable (and not None) Python objects.
         attr_dict : dictionary, optional (default= no attributes)
@@ -896,7 +896,7 @@ class Graph(object):
 
         Parameters
         ----------
-        u,v: nodes
+        u, v : nodes
             Remove the edge between nodes u and v.
 
         Raises
@@ -965,7 +965,7 @@ class Graph(object):
 
         Parameters
         ----------
-        u,v : nodes
+        u, v : nodes
             Nodes can be, for example, strings or numbers.
             Nodes must be hashable (and not None) Python objects.
 
@@ -1124,7 +1124,7 @@ class Graph(object):
 
         Parameters
         ----------
-        u,v : nodes
+        u, v : nodes
         default:  any Python object (default=None)
             Value to return if the edge (u,v) is not found.
 
@@ -1595,7 +1595,7 @@ class Graph(object):
 
         Parameters
         ----------
-        u,v : nodes, optional (default=all edges)
+        u, v : nodes, optional (default=all edges)
             If u and v are specified, return the number of edges between
             u and v. Otherwise return the total number of all edges.
 
diff --git a/networkx/classes/multidigraph.py b/networkx/classes/multidigraph.py
index 04fb6bfb..d8cd9990 100644
--- a/networkx/classes/multidigraph.py
+++ b/networkx/classes/multidigraph.py
@@ -38,6 +38,7 @@ class MultiDiGraph(MultiGraph,DiGraph):
         NetworkX graph object.  If the corresponding optional Python
         packages are installed the data can also be a NumPy matrix
         or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
+
     attr : keyword arguments, optional (default= no attributes)
         Attributes to add to graph as key=value pairs.
 
@@ -263,7 +264,7 @@ class MultiDiGraph(MultiGraph,DiGraph):
 
         Parameters
         ----------
-        u,v : nodes
+        u, v : nodes
             Nodes can be, for example, strings or numbers.
             Nodes must be hashable (and not None) Python objects.
         key : hashable identifier, optional (default=lowest unused integer)
@@ -350,7 +351,7 @@ class MultiDiGraph(MultiGraph,DiGraph):
 
         Parameters
         ----------
-        u,v: nodes
+        u, v : nodes
             Remove an edge between nodes u and v.
         key : hashable identifier, optional (default=None)
             Used to distinguish multiple edges between a pair of nodes.
diff --git a/networkx/classes/multigraph.py b/networkx/classes/multigraph.py
index 0ed037ff..5a248456 100644
--- a/networkx/classes/multigraph.py
+++ b/networkx/classes/multigraph.py
@@ -37,6 +37,7 @@ class MultiGraph(Graph):
         NetworkX graph object.  If the corresponding optional Python
         packages are installed the data can also be a NumPy matrix
         or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
+
     attr : keyword arguments, optional (default= no attributes)
         Attributes to add to graph as key=value pairs.
 
@@ -264,7 +265,7 @@ class MultiGraph(Graph):
 
         Parameters
         ----------
-        u,v : nodes
+        u, v : nodes
             Nodes can be, for example, strings or numbers.
             Nodes must be hashable (and not None) Python objects.
         key : hashable identifier, optional (default=lowest unused integer)
@@ -424,7 +425,7 @@ class MultiGraph(Graph):
 
         Parameters
         ----------
-        u,v: nodes
+        u, v : nodes
             Remove an edge between nodes u and v.
         key : hashable identifier, optional (default=None)
             Used to distinguish multiple edges between a pair of nodes.
@@ -533,7 +534,7 @@ class MultiGraph(Graph):
 
         Parameters
         ----------
-        u,v : nodes
+        u, v : nodes
             Nodes can be, for example, strings or numbers.
 
         key : hashable identifier, optional (default=None)
@@ -672,9 +673,11 @@ class MultiGraph(Graph):
 
         Parameters
         ----------
-        u,v : nodes
-        default:  any Python object (default=None)
+        u, v : nodes
+
+        default :  any Python object (default=None)
             Value to return if the edge (u,v) is not found.
+
         key : hashable identifier, optional (default=None)
             Return data only for the edge with specified key.
 
@@ -927,7 +930,7 @@ class MultiGraph(Graph):
 
         Parameters
         ----------
-        u,v : nodes, optional (default=all edges)
+        u, v : nodes, optional (default=all edges)
             If u and v are specified, return the number of edges between
             u and v. Otherwise return the total number of all edges.
 
diff --git a/networkx/drawing/layout.py b/networkx/drawing/layout.py
index efc7ed0f..9bbc6f98 100644
--- a/networkx/drawing/layout.py
+++ b/networkx/drawing/layout.py
@@ -111,7 +111,7 @@ def circular_layout(G, dim=2, scale=1, center=None):
     >>> pos=nx.circular_layout(G)
 
     Notes
-    ------
+    -----
     This algorithm currently only works in two dimensions and does not
     try to minimize edge crossings.
 
@@ -165,7 +165,7 @@ def shell_layout(G, nlist=None, dim=2, scale=1, center=None):
     >>> pos = nx.shell_layout(G, shells)
 
     Notes
-    ------
+    -----
     This algorithm currently only works in two dimensions and does not
     try to minimize edge crossings.
 
diff --git a/networkx/drawing/nx_pylab.py b/networkx/drawing/nx_pylab.py
index 00c359eb..1e865f65 100644
--- a/networkx/drawing/nx_pylab.py
+++ b/networkx/drawing/nx_pylab.py
@@ -62,7 +62,7 @@ def draw(G, pos=None, ax=None, hold=None, **kwds):
        Set the Matplotlib hold state.  If True subsequent draw
        commands will be added to the current axes.
 
-    **kwds : optional keywords
+    kwds : optional keywords
        See networkx.draw_networkx() for a description of optional keywords.
 
 
@@ -890,7 +890,7 @@ def draw_circular(G, **kwargs):
     G : graph
        A networkx graph
 
-    **kwargs : optional keywords
+    kwargs : optional keywords
        See networkx.draw_networkx() for a description of optional keywords,
        with the exception of the pos parameter which is not used by this
        function.
@@ -906,7 +906,7 @@ def draw_random(G, **kwargs):
     G : graph
        A networkx graph
 
-    **kwargs : optional keywords
+    kwargs : optional keywords
        See networkx.draw_networkx() for a description of optional keywords,
        with the exception of the pos parameter which is not used by this
        function.
@@ -922,7 +922,7 @@ def draw_spectral(G, **kwargs):
     G : graph
        A networkx graph
 
-    **kwargs : optional keywords
+    kwargs : optional keywords
        See networkx.draw_networkx() for a description of optional keywords,
        with the exception of the pos parameter which is not used by this
        function.
@@ -938,7 +938,7 @@ def draw_spring(G, **kwargs):
     G : graph
        A networkx graph
 
-    **kwargs : optional keywords
+    kwargs : optional keywords
        See networkx.draw_networkx() for a description of optional keywords,
        with the exception of the pos parameter which is not used by this
        function.
@@ -954,7 +954,7 @@ def draw_shell(G, **kwargs):
     G : graph
        A networkx graph
 
-    **kwargs : optional keywords
+    kwargs : optional keywords
        See networkx.draw_networkx() for a description of optional keywords,
        with the exception of the pos parameter which is not used by this
        function.
@@ -976,7 +976,7 @@ def draw_graphviz(G, prog="neato", **kwargs):
     prog : string, optional
       Name of Graphviz layout program
 
-    **kwargs : optional keywords
+    kwargs : optional keywords
        See networkx.draw_networkx() for a description of optional keywords.
     """
     pos = nx.drawing.graphviz_layout(G, prog)
diff --git a/networkx/generators/stochastic.py b/networkx/generators/stochastic.py
index 73f7759f..1447ed81 100644
--- a/networkx/generators/stochastic.py
+++ b/networkx/generators/stochastic.py
@@ -22,8 +22,7 @@ __all__ = ['stochastic_graph']
 
 @not_implemented_for('undirected')
 def stochastic_graph(G, copy=True, weight='weight'):
-    """Returns a right-stochastic representation of the directed graph
-    ``G``.
+    """Returns a right-stochastic representation of directed graph ``G``.
 
     A right-stochastic graph is a weighted digraph in which for each
     node, the sum of the weights of all the out-edges of that node is
@@ -31,8 +30,8 @@ def stochastic_graph(G, copy=True, weight='weight'):
     edge attribute), the reweighting takes that into account.
 
     Parameters
-    -----------
-    G : NetworkX graph
+    ----------
+    G : directed graph
         A :class:`~networkx.DiGraph` or :class:`~networkx.MultiDiGraph`.
 
     copy : boolean, optional
diff --git a/networkx/readwrite/gml.py b/networkx/readwrite/gml.py
index d3c8b852..fe52224b 100644
--- a/networkx/readwrite/gml.py
+++ b/networkx/readwrite/gml.py
@@ -706,7 +706,7 @@ def write_gml(G, path, stringizer=None):
     structure.
 
     Examples
-    ---------
+    --------
     >>> G = nx.path_graph(4)
     >>> nx.write_gml(G, "test.gml")