[Doc] Tutorials re-organization (dmlc#2683)

* reorg * change titles * rm some stale API doc; minor fix * fix docs * add warning * rm new-tutorial run in ci * lint
anirband · Feb 20, 2021 · 8a07ab7 · 8a07ab7
1 parent 0fc6495
commit 8a07ab7
Show file tree

Hide file tree

Showing 68 changed files with 264 additions and 2,177 deletions.
diff --git a/docs/source/api/python/dgl.dataloading.rst b/docs/source/api/python/dgl.dataloading.rst
@@ -19,6 +19,7 @@ and an ``EdgeDataLoader`` for edge/link prediction task.
 .. autoclass:: GraphDataLoader
 
 .. _api-dataloading-neighbor-sampling:
+
 Neighbor Sampler
 -----------------------------
 .. currentmodule:: dgl.dataloading.neighbor

diff --git a/docs/source/api/python/dgl.rst b/docs/source/api/python/dgl.rst
@@ -114,10 +114,33 @@ Utilities for computing adjacency matrix and Lapacian matrix.
     khop_adj
     laplacian_lambda_max
 
-Traversals
+Graph Traversal & Message Propagation
 ------------------------------------------
 
-Utilities for traversing graphs.
+DGL implements graph traversal algorithms implemented as python generators,
+which returns the visited set of nodes or edges (in ID tensor) at each iteration.
+The naming convention is ``<algorithm>_[nodes|edges]_generator``.
+An example usage is as follows.
+
+.. code:: python
+
+    g = ...  # some DGLGraph
+    for nodes in dgl.bfs_nodes_generator(g, 0):
+        do_something(nodes)
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    bfs_nodes_generator
+    bfs_edges_generator
+    topological_nodes_generator
+    dfs_edges_generator
+    dfs_labeled_edges_generator
+
+DGL provides APIs to perform message passing following graph traversal order. ``prop_nodes_XXX``
+calls traversal algorithm ``XXX`` and triggers :func:`~DGLGraph.pull()` on the visited node
+set at each iteration. ``prop_edges_YYY`` applies traversal algorithm ``YYY`` and triggers
+:func:`~DGLGraph.send_and_recv()` on the visited edge set at each iteration.
 
 .. autosummary::
     :toctree: ../../generated/

diff --git a/docs/source/api/python/graph.rst b/docs/source/api/python/graph.rst
diff --git a/docs/source/api/python/graph_store.rst b/docs/source/api/python/graph_store.rst