[docs] updated to current content

docs/index.rst

@@ -29,8 +29,9 @@ If you are comfortable using :py:class:`list`, :py:class:`dict` or other types,
 
 .. code::
 
+    from graphi.types.adjacency_graph import AdjacencyGraph
     # create a graph with initial nodes
-    airports = Graph("New York", "Rio", "Tokyo")
+    airports = AdjacencyGraph("New York", "Rio", "Tokyo")
     # add connections between nodes
     airports["New York":"Rio"] = timedelta(hours=9, minutes=50)
     airports["New York":"Tokyo"] = timedelta(hours=13, minutes=55)
@@ -41,7 +42,7 @@ For example, creating a multigraph is as simple as using multiple edge values:
 
 .. code::
 
-    # add multiple connections between nodes
+    # add multiple connections between nodes -> Multigraph
     airports["Rio":"Tokyo"] = timedelta(days=1, hours=2), timedelta(days=1, hours=3)
 
 With its general-purpose design, ``GraphI`` makes no assumptions about your data.

docs/source/api/graphi.graph_io.csv.rst

@@ -0,0 +1,7 @@
+graphi\.graph\_io\.csv module
+=============================
+
+.. automodule:: graphi.graph_io.csv
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/api/graphi.graph_io.rst

@@ -0,0 +1,15 @@
+graphi\.graph\_io package
+=========================
+
+.. automodule:: graphi.graph_io
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   graphi.graph_io.csv
+

docs/source/api/graphi.operators.interface.rst

@@ -0,0 +1,7 @@
+graphi\.operators\.interface module
+===================================
+
+.. automodule:: graphi.operators.interface
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/api/graphi.operators.rst

@@ -0,0 +1,15 @@
+graphi\.operators package
+=========================
+
+.. automodule:: graphi.operators
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   graphi.operators.interface
+

docs/source/api/graphi.rst

@@ -11,7 +11,8 @@ Subpackages
 
 .. toctree::
 
-    graphi.compatibility
+    graphi.graph_io
+    graphi.operators
     graphi.types
 
 Submodules

docs/source/common_ops.rst

@@ -0,0 +1,14 @@
++++++++++++++++++++++++
+Common Graph Operations
++++++++++++++++++++++++
+
+Many common graph operations map to simple operators in :py:mod:`graphi`.
+Unless parameters are needed, builtin operations usually suffice.
+For example, the outdegree of a node is simply
+
+.. code::
+
+    len(graph[node])
+
+in a directed graph.
+Since :py:mod:`graphi` makes heavy use of data views (instead of copies), this has optimal performance.

graphi/graph_io/csv.py

@@ -17,16 +17,16 @@ class DistanceMatrixLiteral(csv.Dialect):
     """
     CSV dialect for a Graph Matrix Literal, suitable for numeric data and string literals
 
-    ```
-     a   b   c
-     0   2 1.3
-     2   0  .5
-    16  .5   1
-    ```
+    A graph with alphabetic node names and numeric values would look like this::
+
+         a   b   c
+         0   2 1.3
+         2   0  .5
+        16  .5   1
     """
-    #: no explicit delimeters required
+    #: no explicit delimeter between fields
     delimiter = ' '
-    #: string literals can be written as "foo"
+    #: string values are written as "foo", multi-values as '1,2,3'
     quotechar = "'"
     doublequote = False
     #: use regular escaping

graphi/types/adjacency_graph.py

@@ -4,19 +4,20 @@
 import six
 
 
-class AdjacencyListTypeError(TypeError):
-    """AdjacencyList was set to incorrect type"""
-    def __init__(self, edge):
-        TypeError.__init__("AdjacencyList must be None, its node or a mapping, not %r" %
-                           edge.__class__)
-
-
 class AdjacencyGraph(abc.Graph):
-    """
-    Graph storing edge distances via adjacency lists.
+    r"""
+    Graph storing edge distances via adjacency lists
 
     :param source: adjacency information
     :param undirected: whether the graph enforces symmetry
+
+    This graph provides optimal performance for random, direct access to nodes
+    and edges. As it stores individual nodes and edges, it is optimal in both
+    space and time for sparse graphs.
+
+    However, ordering of :py:meth:`nodes`, :py:meth:`edges` and :py:meth:`values`
+    is arbitrary. The expected complexity for searches is the worst case of O(len(:py:meth:`nodes`) = n)
+    and O(len(:py:meth:`edges`) -> n\ :sup:`2`\ ), respectively.
     """
     def __init__(self, *source, undirected=False, max_distance=None):
         self.undirected = undirected
@@ -123,7 +124,7 @@ def __setitem__(self, item, value):
                         self._adjacency[node_to][item] = value[node_to]
                 self._adjacency[item] = value.copy()
             else:
-                raise AdjacencyListTypeError(value)
+                raise abc.AdjacencyListTypeError(value)
 
     def __delitem__(self, item):
         if isinstance(item, slice):