[docs] added description of top level package elements

docs/index.rst

@@ -31,9 +31,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 = AdjacencyGraph("New York", "Rio", "Tokyo")
+    from graphi import graph
+    airports = graph("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)

graphi/__init__.py

@@ -1,10 +1,33 @@
-from . import abc
-from .types import adjacency_graph
+from .abc import Graph as _GraphABC
+from .types.adjacency_graph import AdjacencyGraph as _AdjacencyGraph
 
-#: default graph implementation
-graph = adjacency_graph.AdjacencyGraph
+#: Default graph type implementation
+#:
+#: An implementation of the :py:class:`~graphi.abc.Graph` interface,
+#: suitable for most purposes.
+#: Support of all graph interfaces for both reading and writing is
+#: provided.
+#: The implementation is adequate for most use-cases, and provides
+#: a balance of complexity, performance and storage.
+#:
+#: :see: The corresponding class
+#:       :py:class:`~graphi.types.adjacency_graph.AdjacencyGraph`
+#:       for details.
+graph = _AdjacencyGraph
 
-#: graph ABC/type
-Graph = abc.Graph
+#: Graph :term:`abstract base class` for type checks and virtual subclasses
+#:
+#: The ABC is primarily needed for two cases:
+#:
+#: * Type checking to find graph classes via :py:func:`isinstance`, as in
+#:   ``isinstance(candidate, GraphABC)``.
+#:
+#: * Actual or virtual subclasses acting as implementations of the :py:mod:`graphi`
+#:   interface for type checks.
+#:
+#: :see: The corresponding class
+#:       :py:class:`~graphi.abc.Graph`
+#:       for details.
+GraphABC = _GraphABC
 
-__all__ = ['graph', 'Graph']
+__all__ = ['graph', 'GraphABC']