update rst documentation, include networkx examples

--HG--
extra : convert_revision : svn%3A3ed01bd8-26fb-0310-9e4c-ca1a4053419f/networkx/trunk%40904

9 files changed, 540 insertions, 31 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 9db2672c..09621f7f 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -37,16 +37,18 @@ dist: html
 	(cd build && tar czf dist.tar.gz dist)
 
 generate: build/generate-stamp
+
 build/generate-stamp:
 	mkdir -p build
 	./sphinxext/numpyext/autosummary_generate.py source/reference/*.rst \
 		-p dump.xml -o source/reference/generated 
+	./make_examples_rst.py examples source/examples
 	touch build/generate-stamp
 
 ext-svn:
 	svn co http://sphinx.googlecode.com/svn/contrib/trunk/numpyext sphinxext/numpyext
 
-html: generate
+html: generate 
 	mkdir -p build/html build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 #	python postprocess.py html build/html/*.html
diff --git a/doc/make_examples_rst.py b/doc/make_examples_rst.py
new file mode 100755
index 00000000..c6595e98
--- /dev/null
+++ b/doc/make_examples_rst.py
@@ -0,0 +1,166 @@
+#!/usr/bin/env python
+"""
+generate the rst files for the examples by iterating over the pylab examples
+"""
+# This code was developed from the Matplotlib gen_rst.py module
+# and is distributed with the same license as Matplotlib
+import os, glob
+
+import os
+import re
+import sys
+#fileList = []
+#rootdir = '../../examples'
+
+
+
+def out_of_date(original, derived):
+    """
+    Returns True if derivative is out-of-date wrt original,
+    both of which are full file paths.
+
+    TODO: this check isn't adequate in some cases.  Eg, if we discover
+    a bug when building the examples, the original and derived
+    will be unchanged but we still want to fource a rebuild.  We can
+    manually remove from _static, but we may need another solution
+    """
+    return (not os.path.exists(derived) or
+            os.stat(derived).st_mtime < os.stat(original).st_mtime)
+
+def main(exampledir,sourcedir):    
+
+    noplot_regex = re.compile(r"#\s*-\*-\s*noplot\s*-\*-")
+
+    datad = {}
+    for root, subFolders, files in os.walk(exampledir):
+        for fname in files:
+            if ( fname.startswith('.') or fname.startswith('#') or fname.startswith('_') or
+                 fname.find('.svn')>=0 or not fname.endswith('.py') ):
+                continue
+
+            fullpath = os.path.join(root,fname)
+            contents = file(fullpath).read()
+            # indent
+            relpath = os.path.split(root)[-1]
+            datad.setdefault(relpath, []).append((fullpath, fname, contents))
+
+    subdirs = datad.keys()
+    subdirs.sort()
+
+    fhindex = file(os.path.join(sourcedir,'index.rst'), 'w')
+    fhindex.write("""\
+.. _examples-index:
+
+*****************
+NetworkX Examples
+*****************
+
+.. htmlonly::
+
+    :Release: |version|
+    :Date: |today|
+
+.. toctree::
+    :maxdepth: 2
+
+""")
+
+    for subdir in subdirs:
+        output_dir= os.path.join(sourcedir,subdir)
+        if not os.path.exists(output_dir):
+            os.makedirs(output_dir)
+
+        static_dir = os.path.join(sourcedir, 'static', 'examples')
+        if not os.path.exists(static_dir):
+            os.makedirs(static_dir)
+
+
+        subdirIndexFile = os.path.join(subdir, 'index.rst')
+        fhsubdirIndex = file(os.path.join(output_dir,'index.rst'), 'w')
+        fhindex.write('    %s\n\n'%subdirIndexFile)
+        #thumbdir = '../_static/plot_directive/mpl_examples/%s/thumbnails/'%subdir
+        #for thumbname in glob.glob(os.path.join(thumbdir,'*.png')):
+        #    fhindex.write('    %s\n'%thumbname)
+
+        fhsubdirIndex.write("""\
+.. _%s-examples-index:
+
+
+##############################################
+%s
+##############################################
+
+.. htmlonly::
+
+    :Release: |version|
+    :Date: |today|
+
+.. toctree::
+    :maxdepth: 1
+
+"""%(subdir, subdir.title()))
+
+
+        data = datad[subdir]
+        data.sort()
+
+        #parts = os.path.split(static_dir)
+        #thumb_dir = ('../'*(len(parts)-1)) + os.path.join(static_dir, 'thumbnails')
+
+        for fullpath, fname, contents in data:
+            basename, ext = os.path.splitext(fname)
+            static_file = os.path.join(static_dir, fname)
+            #thumbfile = os.path.join(thumb_dir, '%s.png'%basename)
+            #print '    static_dir=%s, basename=%s, fullpath=%s, fname=%s, thumb_dir=%s, thumbfile=%s'%(static_dir, basename, fullpath, fname, thumb_dir, thumbfile)
+
+            rstfile = '%s.rst'%basename
+            outfile = os.path.join(output_dir, rstfile)
+
+            fhsubdirIndex.write('    %s\n'%rstfile)
+
+            if (not out_of_date(fullpath, static_file) and
+                not out_of_date(fullpath, outfile)):
+                continue
+
+            print '%s/%s'%(subdir,fname)
+
+            fhstatic = file(static_file, 'w')
+            fhstatic.write(contents)
+            fhstatic.close()
+
+            fh = file(outfile, 'w')
+            fh.write('.. _%s-%s:\n\n'%(subdir, basename))
+            base=fname.partition('.')[0]
+            title = '%s'%(base.replace('_',' ').title())
+
+            #title = '<img src=%s> %s example code: %s'%(thumbfile, subdir, fname)
+
+
+            fh.write(title + '\n')
+            fh.write('='*len(title) + '\n\n')
+
+            do_plot = (subdir in ('api',
+                                  'pylab_examples',
+                                  'units') and
+                       not noplot_regex.search(contents))
+
+            if do_plot:
+                fh.write("\n\n.. plot:: %s\n\n::\n\n" % fullpath[3:])
+            else:
+                linkname = os.path.join('..', '..', '_static', 'examples', subdir, fname)
+                fh.write("[`source code <%s>`_]\n\n::\n\n" % linkname)
+
+            # indent the contents
+            contents = '\n'.join(['    %s'%row.rstrip() for row in contents.split('\n')])
+            fh.write(contents)
+
+    #        fh.write('\n\nKeywords: python, matplotlib, pylab, example, codex (see :ref:`how-to-search-examples`)')
+            fh.close()
+
+        fhsubdirIndex.close()
+
+    fhindex.close()
+
+if __name__ == '__main__':
+    import sys
+    main(sys.argv[1],sys.argv[2])
diff --git a/doc/source/contents.rst b/doc/source/contents.rst
index 28c6f657..5c8247ed 100644
--- a/doc/source/contents.rst
+++ b/doc/source/contents.rst
@@ -18,8 +18,9 @@ NetworkX documentation
    reference/index
    examples/index
    gallery/index
+   download
 
-
+   
 Indices and tables
 ==================
 
diff --git a/doc/source/reference/classes.digraph.rst b/doc/source/reference/classes.digraph.rst
index be6d475b..24914bfe 100644
--- a/doc/source/reference/classes.digraph.rst
+++ b/doc/source/reference/classes.digraph.rst
@@ -1,10 +1,83 @@
 .. _digraph:
 
-
+=======
 DiGraph
+=======
+
+Overview
+--------
+.. currentmodule:: networkx
+.. autoclass:: DiGraph
+
+Methods
 -------
 
-.. autoclass:: networkx.classes.DiGraph
-   :members:
-   :undoc-members:
-   :inherited-members:
+.. autosummary::
+   :toctree: generated/
+
+   DiGraph.add_node
+   DiGraph.add_nodes_from
+   DiGraph.remove_node
+   DiGraph.remove_nodes_from
+   DiGraph.nodes_iter
+   DiGraph.nodes
+   DiGraph.number_of_nodes
+   DiGraph.order
+   DiGraph.has_node
+   DiGraph.add_edge
+   DiGraph.add_edges_from
+   DiGraph.remove_edge
+   DiGraph.remove_edges_from
+   DiGraph.has_neighbor
+   DiGraph.has_edge
+   DiGraph.neighbors
+   DiGraph.neighbors_iter
+   DiGraph.edges
+   DiGraph.edges_iter
+   DiGraph.get_edge
+   DiGraph.adjacency_list
+   DiGraph.adjacency_iter
+   DiGraph.degree
+   DiGraph.degree_iter
+   DiGraph.clear
+   DiGraph.copy
+   DiGraph.to_directed
+   DiGraph.to_undirected
+   DiGraph.subgraph
+   DiGraph.nodes_with_selfloops
+   DiGraph.selfloop_edges
+   DiGraph.number_of_selfloops
+   DiGraph.size
+   DiGraph.number_of_edges
+   DiGraph.add_star
+   DiGraph.add_path
+   DiGraph.add_cycle
+   DiGraph.nbunch_iter
+
+
+DiGraph only
+------------
+.. autosummary::
+   :toctree: generated/
+
+   DiGraph.has_successor
+   DiGraph.has_predecessor
+   DiGraph.successors
+   DiGraph.predecessors
+   DiGraph.successors_iter
+   DiGraph.predecessors_iter
+   DiGraph.reverse
+
+Special Methods
+---------------
+
+.. autosummary::
+   :toctree: generated/
+
+
+   DiGraph.__init__
+   DiGraph.__str__
+   DiGraph.__iter__
+   DiGraph.__contains__
+   DiGraph.__len__
+   DiGraph.__getitem__
diff --git a/doc/source/reference/classes.labeleddigraph.rst b/doc/source/reference/classes.labeleddigraph.rst
index faae7c8f..11c29720 100644
--- a/doc/source/reference/classes.labeleddigraph.rst
+++ b/doc/source/reference/classes.labeleddigraph.rst
@@ -1,10 +1,83 @@
 .. _labeleddigraph:
 
-
+===============
 Labeled DiGraph
+===============
+
+Overview
+--------
+.. currentmodule:: networkx
+.. autoclass:: LabeledDiGraph
+
+Methods
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   LabeledDiGraph.add_node
+   LabeledDiGraph.add_nodes_from
+   LabeledDiGraph.remove_node
+   LabeledDiGraph.remove_nodes_from
+   LabeledDiGraph.nodes_iter
+   LabeledDiGraph.nodes
+   LabeledDiGraph.number_of_nodes
+   LabeledDiGraph.order
+   LabeledDiGraph.has_node
+   LabeledDiGraph.add_edge
+   LabeledDiGraph.add_edges_from
+   LabeledDiGraph.remove_edge
+   LabeledDiGraph.remove_edges_from
+   LabeledDiGraph.has_neighbor
+   LabeledDiGraph.has_edge
+   LabeledDiGraph.neighbors
+   LabeledDiGraph.neighbors_iter
+   LabeledDiGraph.edges
+   LabeledDiGraph.edges_iter
+   LabeledDiGraph.get_edge
+   LabeledDiGraph.adjacency_list
+   LabeledDiGraph.adjacency_iter
+   LabeledDiGraph.degree
+   LabeledDiGraph.degree_iter
+   LabeledDiGraph.clear
+   LabeledDiGraph.copy
+   LabeledDiGraph.to_directed
+   LabeledDiGraph.to_undirected
+   LabeledDiGraph.subgraph
+   LabeledDiGraph.nodes_with_selfloops
+   LabeledDiGraph.selfloop_edges
+   LabeledDiGraph.number_of_selfloops
+   LabeledDiGraph.size
+   LabeledDiGraph.number_of_edges
+   LabeledDiGraph.add_star
+   LabeledDiGraph.add_path
+   LabeledDiGraph.add_cycle
+   LabeledDiGraph.nbunch_iter
+
+
+LabeledDiGraph only
+-------------------
+.. autosummary::
+   :toctree: generated/
+
+   LabeledDiGraph.has_successor
+   LabeledDiGraph.has_predecessor
+   LabeledDiGraph.successors
+   LabeledDiGraph.predecessors
+   LabeledDiGraph.successors_iter
+   LabeledDiGraph.predecessors_iter
+   LabeledDiGraph.reverse
+
+Special Methods
 ---------------
 
-.. autoclass:: networkx.classes.LabeledDiGraph
-   :members:
-   :undoc-members:
-   :inherited-members:
+.. autosummary::
+   :toctree: generated/
+
+
+   LabeledDiGraph.__init__
+   LabeledDiGraph.__str__
+   LabeledDiGraph.__iter__
+   LabeledDiGraph.__contains__
+   LabeledDiGraph.__len__
+   LabeledDiGraph.__getitem__
diff --git a/doc/source/reference/classes.labeledgraph.rst b/doc/source/reference/classes.labeledgraph.rst
index fd30f53d..ac9b1677 100644
--- a/doc/source/reference/classes.labeledgraph.rst
+++ b/doc/source/reference/classes.labeledgraph.rst
@@ -1,10 +1,70 @@
 .. _labeledgraph:
 
-
+=============
 Labeled Graph
--------------
+=============
+
+Overview
+--------
+.. currentmodule:: networkx
+.. autoclass:: LabeledGraph
+
+Methods
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   LabeledGraph.add_node
+   LabeledGraph.add_nodes_from
+   LabeledGraph.remove_node
+   LabeledGraph.remove_nodes_from
+   LabeledGraph.nodes_iter
+   LabeledGraph.nodes
+   LabeledGraph.number_of_nodes
+   LabeledGraph.order
+   LabeledGraph.has_node
+   LabeledGraph.add_edge
+   LabeledGraph.add_edges_from
+   LabeledGraph.remove_edge
+   LabeledGraph.remove_edges_from
+   LabeledGraph.has_neighbor
+   LabeledGraph.has_edge
+   LabeledGraph.neighbors
+   LabeledGraph.neighbors_iter
+   LabeledGraph.edges
+   LabeledGraph.edges_iter
+   LabeledGraph.get_edge
+   LabeledGraph.adjacency_list
+   LabeledGraph.adjacency_iter
+   LabeledGraph.degree
+   LabeledGraph.degree_iter
+   LabeledGraph.clear
+   LabeledGraph.copy
+   LabeledGraph.to_directed
+   LabeledGraph.to_undirected
+   LabeledGraph.subgraph
+   LabeledGraph.nodes_with_selfloops
+   LabeledGraph.selfloop_edges
+   LabeledGraph.number_of_selfloops
+   LabeledGraph.size
+   LabeledGraph.number_of_edges
+   LabeledGraph.add_star
+   LabeledGraph.add_path
+   LabeledGraph.add_cycle
+   LabeledGraph.nbunch_iter
+
+
+Special Methods
+---------------
+
+.. autosummary::
+   :toctree: generated/
+
 
-.. autoclass:: networkx.classes.LabeledGraph
-   :members:
-   :undoc-members:
-   :inherited-members:
+   LabeledGraph.__init__
+   LabeledGraph.__str__
+   LabeledGraph.__iter__
+   LabeledGraph.__contains__
+   LabeledGraph.__len__
+   LabeledGraph.__getitem__
diff --git a/doc/source/reference/classes.multidigraph.rst b/doc/source/reference/classes.multidigraph.rst
index 7bb83626..39f56483 100644
--- a/doc/source/reference/classes.multidigraph.rst
+++ b/doc/source/reference/classes.multidigraph.rst
@@ -1,10 +1,84 @@
 .. _multidigraph:
 
 
+============
 MultiDiGraph
-------------
+============
 
-.. autoclass:: networkx.classes.MultiDiGraph
-   :members:
-   :undoc-members:
-   :inherited-members:
+Overview
+--------
+.. currentmodule:: networkx
+.. autoclass:: MultiDiGraph
+
+Methods
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   MultiDiGraph.add_node
+   MultiDiGraph.add_nodes_from
+   MultiDiGraph.remove_node
+   MultiDiGraph.remove_nodes_from
+   MultiDiGraph.nodes_iter
+   MultiDiGraph.nodes
+   MultiDiGraph.number_of_nodes
+   MultiDiGraph.order
+   MultiDiGraph.has_node
+   MultiDiGraph.add_edge
+   MultiDiGraph.add_edges_from
+   MultiDiGraph.remove_edge
+   MultiDiGraph.remove_edges_from
+   MultiDiGraph.has_neighbor
+   MultiDiGraph.has_edge
+   MultiDiGraph.neighbors
+   MultiDiGraph.neighbors_iter
+   MultiDiGraph.edges
+   MultiDiGraph.edges_iter
+   MultiDiGraph.get_edge
+   MultiDiGraph.adjacency_list
+   MultiDiGraph.adjacency_iter
+   MultiDiGraph.degree
+   MultiDiGraph.degree_iter
+   MultiDiGraph.clear
+   MultiDiGraph.copy
+   MultiDiGraph.to_directed
+   MultiDiGraph.to_undirected
+   MultiDiGraph.subgraph
+   MultiDiGraph.nodes_with_selfloops
+   MultiDiGraph.selfloop_edges
+   MultiDiGraph.number_of_selfloops
+   MultiDiGraph.size
+   MultiDiGraph.number_of_edges
+   MultiDiGraph.add_star
+   MultiDiGraph.add_path
+   MultiDiGraph.add_cycle
+   MultiDiGraph.nbunch_iter
+
+
+MultiDiGraph only
+-----------------
+.. autosummary::
+   :toctree: generated/
+
+   MultiDiGraph.has_successor
+   MultiDiGraph.has_predecessor
+   MultiDiGraph.successors
+   MultiDiGraph.predecessors
+   MultiDiGraph.successors_iter
+   MultiDiGraph.predecessors_iter
+   MultiDiGraph.reverse
+
+Special Methods
+---------------
+
+.. autosummary::
+   :toctree: generated/
+
+
+   MultiDiGraph.__init__
+   MultiDiGraph.__str__
+   MultiDiGraph.__iter__
+   MultiDiGraph.__contains__
+   MultiDiGraph.__len__
+   MultiDiGraph.__getitem__
diff --git a/doc/source/reference/classes.multigraph.rst b/doc/source/reference/classes.multigraph.rst
index 37b64aa5..da2d75f7 100644
--- a/doc/source/reference/classes.multigraph.rst
+++ b/doc/source/reference/classes.multigraph.rst
@@ -1,10 +1,70 @@
 .. _multigraph:
 
-
+==========
 MultiGraph
-----------
+==========
+
+Overview
+--------
+.. currentmodule:: networkx
+.. autoclass:: MultiGraph
+
+Methods
+-------
+
+.. autosummary::
+   :toctree: generated/
+
+   MultiGraph.add_node
+   MultiGraph.add_nodes_from
+   MultiGraph.remove_node
+   MultiGraph.remove_nodes_from
+   MultiGraph.nodes_iter
+   MultiGraph.nodes
+   MultiGraph.number_of_nodes
+   MultiGraph.order
+   MultiGraph.has_node
+   MultiGraph.add_edge
+   MultiGraph.add_edges_from
+   MultiGraph.remove_edge
+   MultiGraph.remove_edges_from
+   MultiGraph.has_neighbor
+   MultiGraph.has_edge
+   MultiGraph.neighbors
+   MultiGraph.neighbors_iter
+   MultiGraph.edges
+   MultiGraph.edges_iter
+   MultiGraph.get_edge
+   MultiGraph.adjacency_list
+   MultiGraph.adjacency_iter
+   MultiGraph.degree
+   MultiGraph.degree_iter
+   MultiGraph.clear
+   MultiGraph.copy
+   MultiGraph.to_directed
+   MultiGraph.to_undirected
+   MultiGraph.subgraph
+   MultiGraph.nodes_with_selfloops
+   MultiGraph.selfloop_edges
+   MultiGraph.number_of_selfloops
+   MultiGraph.size
+   MultiGraph.number_of_edges
+   MultiGraph.add_star
+   MultiGraph.add_path
+   MultiGraph.add_cycle
+   MultiGraph.nbunch_iter
+
+
+Special Methods
+---------------
+
+.. autosummary::
+   :toctree: generated/
+
 
-.. autoclass:: networkx.classes.MultiGraph
-   :members:
-   :undoc-members:
-   :inherited-members:
+   MultiGraph.__init__
+   MultiGraph.__str__
+   MultiGraph.__iter__
+   MultiGraph.__contains__
+   MultiGraph.__len__
+   MultiGraph.__getitem__
diff --git a/doc/source/reference/drawing.rst b/doc/source/reference/drawing.rst
index b1b7399d..a96b869b 100644
--- a/doc/source/reference/drawing.rst
+++ b/doc/source/reference/drawing.rst
@@ -1,8 +1,8 @@
 .. _drawing:
 
 
-Reading and Writing
-*******************
+Drawing
+*******
 
 .. currentmodule:: networkx