[Doc] Re-organize API docs and tutorials (#1222)

* reorg tutorials and api docs

* fix

docs/source/api/python/batch.rst

 .. _apibatch:
 
-BatchedDGLGraph -- Enable batched graph operations
+dgl.batched_graph
 ==================================================
 
 .. currentmodule:: dgl

docs/source/api/python/batch_heterograph.rst

 .. _apibatch_heterograph:
 
-BatchedDGLHeteroGraph -- Enable batched graph operations for heterographs
+dgl.batched_heterograph
 =========================================================================
 
 .. currentmodule:: dgl

docs/source/api/python/data.rst

 .. _apidata:
 
-Dataset
-=======
+dgl.data
+=========
 
 .. currentmodule:: dgl.data
 

docs/source/api/python/function.rst

 .. _apifunction:
 
-Builtin functions
-=================
+.. currentmodule:: dgl.function
 
-.. automodule:: dgl.function
+dgl.function
+==================================
+
+In DGL, message passing is expressed by two APIs:
+
+- ``send(edges, message_func)`` for computing the messages along the given edges.
+- ``recv(nodes, reduce_func)`` for collecting the incoming messages, perform aggregation and so on.
+
+Although the two-stage abstraction can cover all the models that are defined in the message
+passing paradigm, it is inefficient because it requires storing explicit messages. See the DGL 
+`blog post <https://www.dgl.ai/blog/2019/05/04/kernel.html>`_ for more
+details and performance results.
+
+Our solution, also explained in the blog post, is to fuse the two stages into one kernel so no
+explicit messages are generated and stored. To achieve this, we recommend using our **built-in
+message and reduce functions** so that DGL can analyze and map them to fused dedicated kernels. Here
+are some examples (in PyTorch syntax).
+
+.. code:: python
+   
+   import dgl
+   import dgl.function as fn
+   import torch as th
+   g = ... # create a DGLGraph
+   g.ndata['h'] = th.randn((g.number_of_nodes(), 10)) # each node has feature size 10
+   g.edata['w'] = th.randn((g.number_of_edges(), 1))  # each edge has feature size 1
+   # collect features from source nodes and aggregate them in destination nodes
+   g.update_all(fn.copy_u('h', 'm'), fn.sum('m', 'h_sum'))
+   # multiply source node features with edge weights and aggregate them in destination nodes
+   g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.max('m', 'h_max'))
+   # compute edge embedding by multiplying source and destination node embeddings
+   g.apply_edges(fn.u_mul_v('h', 'h', 'w_new'))
+
+``fn.copy_u``, ``fn.u_mul_e``, ``fn.u_mul_v`` are built-in message functions, while ``fn.sum``
+and ``fn.max`` are built-in reduce functions. We use ``u``, ``v`` and ``e`` to represent
+source nodes, destination nodes, and edges among them, respectively. Hence, ``copy_u`` copies the source
+node data as the messages, ``u_mul_e`` multiplies source node features with edge features, for example.
+
+To define a unary message function (e.g. ``copy_u``) specify one input feature name and one output
+message name. To define a binary message function (e.g. ``u_mul_e``) specify
+two input feature names and one output message name. During the computation,
+the message function will read the data under the given names, perform computation, and return
+the output using the output name. For example, the above ``fn.u_mul_e('h', 'w', 'm')`` is
+the same as the following user-defined function:
+
+.. code:: python
+
+   def udf_u_mul_e(edges):
+      return {'m' : edges.src['h'] * edges.data['w']}
+
+To define a reduce function, one input message name and one output node feature name
+need to be specified. For example, the above ``fn.max('m', 'h_max')`` is the same as the
+following user-defined function:
+
+.. code:: python
+
+   def udf_max(nodes):
+      return {'h_max' : th.max(nodes.mailbox['m'], 1)[0]}
+
+Broadcasting is supported for binary message function, which means the tensor arguments
+can be automatically expanded to be of equal sizes. The supported broadcasting semantic
+is standard and matches `NumPy <https://docs.scipy.org/doc/numpy/user/basics.broadcasting.html>`_
+and `PyTorch <https://pytorch.org/docs/stable/notes/broadcasting.html>`_. If you are not familiar
+with broadcasting, see the linked topics to learn more. In the
+above example, ``fn.u_mul_e`` will perform broadcasted multiplication automatically because
+the node feature ``'h'`` and the edge feature ``'w'`` are of different shapes, but they can be broadcast.
+
+All DGL's built-in functions support both CPU and GPU and backward computation so they
+can be used in any `autograd` system. Also, built-in functions can be used not only in ``update_all``
+or ``apply_edges`` as shown in the example, but wherever message and reduce functions are
+required (e.g. ``pull``, ``push``, ``send_and_recv``).
+
+Here is a cheatsheet of all the DGL built-in functions.
+
++-------------------------+-----------------------------------------------------------------+-----------------------+
+| Category                | Functions                                                       | Memo                  |
++=========================+=================================================================+=======================+
+| Unary message function  | ``copy_u``                                                      |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``copy_e``                                                      |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``copy_src``                                                    |  alias of ``copy_u``  |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``copy_edge``                                                   |  alias of ``copy_e``  |
++-------------------------+-----------------------------------------------------------------+-----------------------+
+| Binary message function | ``u_add_v``, ``u_sub_v``, ``u_mul_v``, ``u_div_v``, ``u_dot_v`` |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``u_add_e``, ``u_sub_e``, ``u_mul_e``, ``u_div_e``, ``u_dot_e`` |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``v_add_u``, ``v_sub_u``, ``v_mul_u``, ``v_div_u``, ``v_dot_u`` |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``v_add_e``, ``v_sub_e``, ``v_mul_e``, ``v_div_e``, ``v_dot_e`` |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``e_add_u``, ``e_sub_u``, ``e_mul_u``, ``e_div_u``, ``e_dot_u`` |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``e_add_v``, ``e_sub_v``, ``e_mul_v``, ``e_div_v``, ``e_dot_v`` |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``src_mul_edge``                                                |  alias of ``u_mul_e`` |
++-------------------------+-----------------------------------------------------------------+-----------------------+
+| Reduce function         | ``max``                                                         |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``min``                                                         |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``sum``                                                         |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``prod``                                                        |                       |
+|                         +-----------------------------------------------------------------+-----------------------+
+|                         | ``mean``                                                        |                       |
++-------------------------+-----------------------------------------------------------------+-----------------------+
 
 Message functions
 -----------------

docs/source/api/python/graph.rst

 .. _apigraph:
 
-DGLGraph -- Untyped graph with node/edge features
+dgl.DGLGraph
 =========================================
 
 .. currentmodule:: dgl

docs/source/api/python/heterograph.rst

 .. _apiheterograph:
 
-DGLHeteroGraph -- Typed graph with node/edge features
+dgl.DGLHeteroGraph
 =====================================================
 
 .. currentmodule:: dgl

docs/source/api/python/index.rst

@@ -6,9 +6,10 @@ API Reference
 
    graph
    heterograph
-   init
    batch
    batch_heterograph
+   nn
+   init
    function
    traversal
    propagate
@@ -16,7 +17,6 @@ API Reference
    sampler
    data
    transform
-   nn
    subgraph
    graph_store
    nodeflow

docs/source/api/python/model_zoo.rst

 .. _apimodelzoo:
 
-Model Zoo
-=========
+dgl.model_zoo
+==============
 
 .. currentmodule:: dgl.model_zoo
 

docs/source/api/python/nn.rst

 .. _apinn:
 
-NN Modules
+dgl.nn
 ==========
 
 .. automodule:: dgl.nn

docs/source/api/python/nodeflow.rst

 .. _apinodeflow:
 
-NodeFlow -- Graph sampled from a large graph
-============================================
+dgl.nodeflow
+==============
 
 .. currentmodule:: dgl
 .. autoclass:: NodeFlow

docs/source/api/python/propagate.rst

-Message Propagation
-===================
+dgl.propagate
+===============
 
 .. automodule:: dgl.propagate
 
+Propagate messages and perform computation 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/
 

docs/source/api/python/random.rst

 .. _apirandom:
 
-DGL Random Number Generator Controls
+dgl.random
 ====================================
 
 .. automodule:: dgl.random
 
+Utilities used to control DGL's random number generator.
+
 .. autosummary::
     :toctree: ../../generated
 

docs/source/api/python/sampler.rst

 .. apisampler
 
-Graph samplers
-==============
+dgl.contrib.sampling
+======================
+
+Module for sampling algorithms on graph. Each algorithm is implemented as a
+data loader, which produces sampled subgraphs (called Nodeflow) at each
+iteration.
 
 .. autofunction:: dgl.contrib.sampling.sampler.NeighborSampler
 .. autofunction:: dgl.contrib.sampling.sampler.LayerSampler

docs/source/api/python/subgraph.rst

 .. _apisubgraph:
 
-DGLSubGraph -- Class for subgraph data structure
+dgl.subgraph
 ================================================
 
 .. currentmodule:: dgl.subgraph

docs/source/api/python/transform.rst

 .. _api-transform:
 
-Transform -- Graph Transformation
+dgl.transform
 =================================
 
 .. automodule:: dgl.transform
 
+Common algorithms on graphs.
+
 .. autosummary::
     :toctree: ../../generated/
 

docs/source/api/python/traversal.rst

-Graph Traversal
+dgl.traversal
 ===============
 
 .. automodule:: dgl.traversal
 
+Graph traversal algorithms implemented as python generators, which returns the visited set
+of nodes or edges 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/
 

docs/source/api/python/udf.rst

 .. _apiudf:
 
-User-defined function related data structures
+dgl.udf
 ==================================================
 
 .. currentmodule:: dgl.udf
-.. automodule:: dgl.udf
 
-There are two types of user-defined functions in DGL:
+User-defined functions (UDFs) are flexible ways to configure message passing computation.
+There are two types of UDFs in DGL:
 
 * **Node UDF** of signature ``NodeBatch -> dict``. The argument represents
   a batch of nodes. The returned dictionary should have ``str`` type key and ``tensor``
@@ -15,7 +15,7 @@ There are two types of user-defined functions in DGL:
   a batch of edges. The returned dictionary should have ``str`` type key and ``tensor``
   type values.
 
-Note: the size of the batch dimension is determined by the DGL framework
+The size of the batch dimension is determined by the DGL framework
 for good efficiency and small memory footprint. Users should not make
 assumption in the batch dimension.
 

docs/source/conf.py

@@ -195,9 +195,8 @@ intersphinx_mapping = {
 from sphinx_gallery.sorting import FileNameSortKey
 
 examples_dirs = ['../../tutorials/basics',
-                 '../../tutorials/models',
-                 '../../tutorials/hetero']  # path to find sources
-gallery_dirs = ['tutorials/basics','tutorials/models','tutorials/hetero']  # path to generate docs
+                 '../../tutorials/models']  # path to find sources
+gallery_dirs = ['tutorials/basics', 'tutorials/models']  # path to generate docs
 reference_url = {
     'dgl' : None,
     'numpy': 'http://docs.scipy.org/doc/numpy/',

docs/source/features/builtin.rst

-.. currentmodule:: dgl
-
-Built-in message passing functions
-=================================
-
-In DGL, message passing is expressed by two APIs:
-
-- ``send(edges, message_func)`` for computing the messages along the given edges.
-- ``recv(nodes, reduce_func)`` for collecting the incoming messages, perform aggregation and so on.
-
-Although the two-stage abstraction can cover all the models that are defined in the message
-passing paradigm, it is inefficient because it requires storing explicit messages. See the DGL 
-`blog post <https://www.dgl.ai/blog/2019/05/04/kernel.html>`_ for more
-details and performance results.
-
-Our solution, also explained in the blog post, is to fuse the two stages into one kernel so no
-explicit messages are generated and stored. To achieve this, we recommend using our built-in
-message and reduce functions so that DGL can analyze and map them to fused dedicated kernels. Here
-are some examples (in PyTorch syntax).
-
-.. code:: python
-   
-   import dgl
-   import dgl.function as fn
-   import torch as th
-   g = ... # create a DGLGraph
-   g.ndata['h'] = th.randn((g.number_of_nodes(), 10)) # each node has feature size 10
-   g.edata['w'] = th.randn((g.number_of_edges(), 1))  # each edge has feature size 1
-   # collect features from source nodes and aggregate them in destination nodes
-   g.update_all(fn.copy_u('h', 'm'), fn.sum('m', 'h_sum'))
-   # multiply source node features with edge weights and aggregate them in destination nodes
-   g.update_all(fn.u_mul_e('h', 'w', 'm'), fn.max('m', 'h_max'))
-   # compute edge embedding by multiplying source and destination node embeddings
-   g.apply_edges(fn.u_mul_v('h', 'h', 'w_new'))
-
-``fn.copy_u``, ``fn.u_mul_e``, ``fn.u_mul_v`` are built-in message functions, while ``fn.sum``
-and ``fn.max`` are built-in reduce functions. We use ``u``, ``v`` and ``e`` to represent
-source nodes, destination nodes, and edges among them, respectively. Hence, ``copy_u`` copies the source
-node data as the messages, ``u_mul_e`` multiplies source node features with edge features, for example.
-
-To define a unary message function (e.g. ``copy_u``) specify one input feature name and one output
-message name. To define a binary message function (e.g. ``u_mul_e``) specify
-two input feature names and one output message name. During the computation,
-the message function will read the data under the given names, perform computation, and return
-the output using the output name. For example, the above ``fn.u_mul_e('h', 'w', 'm')`` is
-the same as the following user-defined function:
-
-.. code:: python
-
-   def udf_u_mul_e(edges):
-      return {'m' : edges.src['h'] * edges.data['w']}
-
-To define a reduce function, one input message name and one output node feature name
-need to be specified. For example, the above ``fn.max('m', 'h_max')`` is the same as the
-following user-defined function:
-
-.. code:: python
-
-   def udf_max(nodes):
-      return {'h_max' : th.max(nodes.mailbox['m'], 1)[0]}
-
-Broadcasting is supported for binary message function, which means the tensor arguments
-can be automatically expanded to be of equal sizes. The supported broadcasting semantic
-is standard and matches `NumPy <https://docs.scipy.org/doc/numpy/user/basics.broadcasting.html>`_
-and `PyTorch <https://pytorch.org/docs/stable/notes/broadcasting.html>`_. If you are not familiar
-with broadcasting, see the linked topics to learn more. In the
-above example, ``fn.u_mul_e`` will perform broadcasted multiplication automatically because
-the node feature ``'h'`` and the edge feature ``'w'`` are of different shapes, but they can be broadcast.
-
-All DGL's built-in functions support both CPU and GPU and backward computation so they
-can be used in any `autograd` system. Also, built-in functions can be used not only in ``update_all``
-or ``apply_edges`` as shown in the example, but wherever message and reduce functions are
-required (e.g. ``pull``, ``push``, ``send_and_recv``).
-
-Here is a cheatsheet of all the DGL built-in functions.
-
-+-------------------------+-----------------------------------------------------------------+-----------------------+
-| Category                | Functions                                                       | Memo                  |
-+=========================+=================================================================+=======================+
-| Unary message function  | ``copy_u``                                                      |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``copy_e``                                                      |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``copy_src``                                                    |  alias of ``copy_u``  |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``copy_edge``                                                   |  alias of ``copy_e``  |
-+-------------------------+-----------------------------------------------------------------+-----------------------+
-| Binary message function | ``u_add_v``, ``u_sub_v``, ``u_mul_v``, ``u_div_v``, ``u_dot_v`` |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``u_add_e``, ``u_sub_e``, ``u_mul_e``, ``u_div_e``, ``u_dot_e`` |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``v_add_u``, ``v_sub_u``, ``v_mul_u``, ``v_div_u``, ``v_dot_u`` |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``v_add_e``, ``v_sub_e``, ``v_mul_e``, ``v_div_e``, ``v_dot_e`` |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``e_add_u``, ``e_sub_u``, ``e_mul_u``, ``e_div_u``, ``e_dot_u`` |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``e_add_v``, ``e_sub_v``, ``e_mul_v``, ``e_div_v``, ``e_dot_v`` |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``src_mul_edge``                                                |  alias of ``u_mul_e`` |
-+-------------------------+-----------------------------------------------------------------+-----------------------+
-| Reduce function         | ``max``                                                         |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``min``                                                         |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``sum``                                                         |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``prod``                                                        |                       |
-|                         +-----------------------------------------------------------------+-----------------------+
-|                         | ``mean``                                                        |                       |
-+-------------------------+-----------------------------------------------------------------+-----------------------+
-
-Next Step
----------
-* To learn how built-in functions are used to implement Graph Neural
-  Network layers See the :mod:`dgl.nn` module.

docs/source/features/nn.rst

-.. currentmodule:: dgl
-
-Graph neural network modules
-===============
-
-This topic provides a link to several high-level, pre-defined modules you can use to build graph neural networks (NN).
-
-
-.. toctree::
-   :glob:
-   :caption: NN Modules
- 
-   ../api/python/nn
-
-
-Contribution guide
-~~~~~~~~~~~~~~~~~~~~~
-
-We welcome your contribution! If you want a model to be implemented in DGL as an NN module,
-please `create an issue <https://github.com/dmlc/dgl/issues>`_ and use this title style: "[Feature Request] NN Module XXXModel".
-
-If you want to contribute an NN module, please `create a pull request <https://github.com/dmlc/dgl/pulls>`_ and use this title style: "[NN] XXXModel in MXNet/PyTorch NN Modules". A team member will review the pull request.