[Doc] Reorg doc (#1989)

docs/source/api/python/batch_heterograph.rst

-.. _apibatch_heterograph:
-
-dgl.batched_heterograph
-=========================================================================
-
-.. currentmodule:: dgl
-.. autoclass:: BatchedDGLHeteroGraph
-
-Merge and decompose
--------------------
-
-.. autosummary::
-    :toctree: ../../generated/
-
-    batch_hetero
-    unbatch_hetero
-
-Query batch summary
-----------------------
-
-.. autosummary::
-    :toctree: ../../generated/
-
-    BatchedDGLHeteroGraph.batch_size
-    BatchedDGLHeteroGraph.batch_num_nodes
-    BatchedDGLHeteroGraph.batch_num_edges

docs/source/api/python/dgl.DGLGraph.rst

+.. _apigraph:
+
+dgl.DGLHeteroGraph
+=====================================================
+
+.. currentmodule:: dgl
+.. autoclass:: DGLHeteroGraph
+
+Querying metagraph structure
+----------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    DGLHeteroGraph.ntypes
+    DGLHeteroGraph.etypes
+    DGLHeteroGraph.canonical_etypes
+    DGLHeteroGraph.metagraph
+    DGLHeteroGraph.to_canonical_etype
+    DGLHeteroGraph.get_ntype_id
+    DGLHeteroGraph.get_etype_id
+
+Querying graph structure
+------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    DGLHeteroGraph.number_of_nodes
+    DGLHeteroGraph.number_of_edges
+    DGLHeteroGraph.is_multigraph
+    DGLHeteroGraph.has_nodes
+    DGLHeteroGraph.has_edges_between
+    DGLHeteroGraph.predecessors
+    DGLHeteroGraph.successors
+    DGLHeteroGraph.edge_ids
+    DGLHeteroGraph.find_edges
+    DGLHeteroGraph.in_edges
+    DGLHeteroGraph.out_edges
+    DGLHeteroGraph.all_edges
+    DGLHeteroGraph.in_degrees
+    DGLHeteroGraph.out_degrees
+
+Querying and manipulating sparse format
+---------------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    DGLHeteroGraph.format_in_use
+    DGLHeteroGraph.restrict_format
+    DGLHeteroGraph.to_format
+
+Querying and manipulating index data type
+-----------------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    DGLHeteroGraph.idtype
+    DGLHeteroGraph.long
+    DGLHeteroGraph.int
+
+Using Node/edge features
+------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    DGLHeteroGraph.nodes
+    DGLHeteroGraph.ndata
+    DGLHeteroGraph.edges
+    DGLHeteroGraph.edata
+    DGLHeteroGraph.node_attr_schemes
+    DGLHeteroGraph.edge_attr_schemes
+    DGLHeteroGraph.set_n_initializer
+    DGLHeteroGraph.set_e_initializer
+    DGLHeteroGraph.local_var
+    DGLHeteroGraph.local_scope
+
+Transforming graph
+------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    DGLHeteroGraph.subgraph
+    DGLHeteroGraph.edge_subgraph
+    DGLHeteroGraph.node_type_subgraph
+    DGLHeteroGraph.edge_type_subgraph
+
+Computing with DGLHeteroGraph
+-----------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    DGLHeteroGraph.apply_nodes
+    DGLHeteroGraph.apply_edges
+    DGLHeteroGraph.send_and_recv
+    DGLHeteroGraph.pull
+    DGLHeteroGraph.push
+    DGLHeteroGraph.update_all
+    DGLHeteroGraph.multi_update_all
+    DGLHeteroGraph.prop_nodes
+    DGLHeteroGraph.prop_edges
+    DGLHeteroGraph.filter_nodes
+    DGLHeteroGraph.filter_edges
+    DGLHeteroGraph.to

docs/source/api/python/dgl.rst

+.. _apidgl:
+
+dgl
+=============================
+
+.. currentmodule:: dgl
+
+Graph Create Ops
+-------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    graph
+    heterograph
+    from_scipy
+    from_networkx
+    bipartite_from_scipy
+    bipartite_from_networkx
+    rand_graph
+    rand_bipartite
+    knn_graph
+    segmented_knn_graph
+
+Subgraph Extraction Routines
+-------------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    node_subgraph
+    edge_subgraph
+    node_type_subgraph
+    edge_type_subgraph
+    in_subgraph
+    out_subgraph
+
+Graph Mutation Routines
+---------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    add_nodes
+    add_edges
+    remove_nodes
+    remove_edges
+    add_self_loop
+    remove_self_loop
+    add_reverse_edges
+
+Graph Transform Routines
+----------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    reverse
+    to_bidirected
+    to_simple
+    to_block
+    compact_graphs
+    to_hetero
+    to_homo
+    to_networkx
+    line_graph
+    khop_graph
+    metapath_reachable_graph
+
+Batching and Reading Out
+-------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    batch
+    unbatch
+    readout_nodes
+    readout_edges
+    sum_nodes
+    sum_edges
+    mean_nodes
+    mean_edges
+    max_nodes
+    max_edges
+    softmax_nodes
+    softmax_edges
+    broadcast_nodes
+    broadcast_edges
+    topk_nodes
+    topk_edges
+
+Adjacency Related Routines
+-------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    khop_adj
+    laplacian_lambda_max
+
+Propagate Messages by Traversals
+------------------------------------------
+
+.. autosummary::
+    :toctree: ../../generated/
+
+    prop_nodes
+    prop_nodes_bfs
+    prop_nodes_topo
+    prop_edges
+    prop_edges_dfs
+
+Utilities
+-----------------------------------------------
+.. autosummary::
+    :toctree: ../../generated/
+
+    seed

docs/source/api/python/index.rst

@@ -4,22 +4,10 @@ API Reference
 .. toctree::
    :maxdepth: 2
 
-   graph
-   heterograph
-   readout
-   batch_heterograph
+   dgl
+   dgl.DGLGraph
+   dgl.data
    nn
-   init
-   ops
-   function
-   traversal
-   propagate
-   udf
-   sampler
+   dgl.ops
+   dgl.function
    sampling
-   data
-   transform
-   graph_store
-   nodeflow
-   random
-   model_zoo

docs/source/guide/data.rst

+Dataset
+========================

docs/source/guide/distributed.rst

+Distributed Training
+============================

docs/source/guide/graph.rst

+Graph
+=====
+
+Graph chapter

docs/source/guide/index.rst

+User Guide
+==========
+
+.. toctree::
+  :maxdepth: 2
+
+  preface
+  graph
+  message
+  data
+  training
+  minibatch
+  distributed

docs/source/guide/message.rst

+Message Passing and Neural Network Modules
+============================================

docs/source/guide/minibatch.rst

+Stochastic Training on Large Graphs
+=====================================

docs/source/guide/preface.rst

+Preface
+=======
+
+Preface chapter

docs/source/guide/training.rst

+Training Graph Neural Networks
+================================

docs/source/index.rst

@@ -30,91 +30,91 @@ generative models on graphs, (previously) difficult-to-parallelize tree-based
 models like TreeLSTM, etc. We also implement some conventional models in DGL
 from a new graphical perspective yielding simplicity.
 
-Relationship of DGL to other frameworks
----------------------------------------
-DGL is designed to be compatible and agnostic to the existing tensor
-frameworks. It provides a backend adapter interface that allows easy porting
-to other tensor-based, autograd-enabled frameworks.
-
 Getting Started
 ---------------
 
-Follow the :doc:`instructions<install/index>` to install DGL.  
-:doc:`DGL at a glance<tutorials/basics/1_first>` is the most common place to get started with.
-It offers a broad experience of using DGL for deep learning on graph data.
-You can learn other basic concepts of DGL through the dedicated tutorials.
+* :doc:`Installation<install/index>`.
+* :doc:`Quickstart tutorial<tutorials/basics/1_first>` for absolute beginners.
+* :doc:`User guide<guide/index>`.
+* :doc:`API reference manual<api/python/index>`.
+* :doc:`End-to-end model tutorials<tutorials/models/index>` for learning DGL by popular models on graphs.
+
+..
+  Follow the :doc:`instructions<install/index>` to install DGL.  
+  :doc:`DGL at a glance<tutorials/basics/1_first>` is the most common place to get started with.
+  It offers a broad experience of using DGL for deep learning on graph data.
+
+  API reference document lists more endetailed specifications of each API and GNN modules,
+  a useful manual for in-depth developers.
+
+  You can learn other basic concepts of DGL through the dedicated tutorials.
 
-* Learn constructing graphs and set/get node and edge features :doc:`here<tutorials/basics/2_basics>`.
-* Learn performing computation on graph using message passing :doc:`here<tutorials/basics/3_pagerank>`.
-* Learn processing multiple graph samples in a batch :doc:`here<tutorials/basics/4_batch>`.
-* Learn working with heterogeneous graph data :doc:`here<tutorials/basics/5_hetero>`.
+  * Learn constructing graphs and set/get node and edge features :doc:`here<tutorials/basics/2_basics>`.
+  * Learn performing computation on graph using message passing :doc:`here<tutorials/basics/3_pagerank>`.
+  * Learn processing multiple graph samples in a batch :doc:`here<tutorials/basics/4_batch>`.
+  * Learn working with heterogeneous graph data :doc:`here<tutorials/basics/5_hetero>`.
 
-End-to-end model tutorials are other good starting points for learning DGL and popular
-models on graphs. The model tutorials are categorized based on the way they utilize DGL APIs.
+  End-to-end model tutorials are other good starting points for learning DGL and popular
+  models on graphs. The model tutorials are categorized based on the way they utilize DGL APIs.
 
-* :ref:`Graph Neural Network and its variant <tutorials1-index>`: Learn how to use DGL to train
+  * :ref:`Graph Neural Network and its variant <tutorials1-index>`: Learn how to use DGL to train
     popular **GNN models** on one input graph.
-* :ref:`Dealing with many small graphs <tutorials2-index>`: Learn how to train models for
+  * :ref:`Dealing with many small graphs <tutorials2-index>`: Learn how to train models for
     many graph samples such as sentence parse trees.
-* :ref:`Generative models <tutorials3-index>`: Learn how to deal with **dynamically-changing graphs**.
-* :ref:`Old (new) wines in new bottle <tutorials4-index>`: Learn how to combine DGL with tensor-based
+  * :ref:`Generative models <tutorials3-index>`: Learn how to deal with **dynamically-changing graphs**.
+  * :ref:`Old (new) wines in new bottle <tutorials4-index>`: Learn how to combine DGL with tensor-based
     DGL framework in a flexible way. Explore new perspective on traditional models by graphs.
-* :ref:`Training on giant graphs <tutorials5-index>`: Learn how to train graph neural networks
+  * :ref:`Training on giant graphs <tutorials5-index>`: Learn how to train graph neural networks
     on giant graphs.
 
-Each tutorial is accompanied with a runnable python script and jupyter notebook that
-can be downloaded. If you would like the tutorials improved, please raise a github issue.
-
-API reference document lists more endetailed specifications of each API and GNN modules,
-a useful manual for in-depth developers.
+  Each tutorial is accompanied with a runnable python script and jupyter notebook that
+  can be downloaded. If you would like the tutorials improved, please raise a github issue.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Installation
+   :caption: Get Started
    :hidden:
    :glob:
 
    install/index
    install/backend
+   tutorials/basics/1_first
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Get Started
+   :maxdepth: 2
+   :caption: User Guide
    :hidden:
    :glob:
 
-   tutorials/basics/index
+   guide/preface
+   guide/graph
+   guide/message
+   guide/data
+   guide/training
+   guide/minibatch
+   guide/distributed
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Tutorials
+   :maxdepth: 2
+   :caption: API Reference
    :hidden:
    :glob:
 
-   tutorials/models/index
+   api/python/dgl
+   api/python/dgl.DGLGraph
+   api/python/dgl.data
+   api/python/nn
+   api/python/dgl.ops
+   api/python/dgl.function
+   api/python/sampling
 
 .. toctree::
-   :maxdepth: 2
-   :caption: API Reference
+   :maxdepth: 3
+   :caption: Model Tutorials
    :hidden:
    :glob:
 
-   api/python/graph
-   api/python/heterograph
-   api/python/ops
-   api/python/readout
-   api/python/batch_heterograph
-   api/python/nn
-   api/python/function
-   api/python/udf
-   api/python/traversal
-   api/python/propagate
-   api/python/transform
-   api/python/sampler
-   api/python/sampling
-   api/python/data
-   api/python/nodeflow
-   api/python/random
+   tutorials/models/index
 
 .. toctree::
    :maxdepth: 1
@@ -135,6 +135,13 @@ a useful manual for in-depth developers.
    env_var
    resources
 
+Relationship of DGL to other frameworks
+---------------------------------------
+DGL is designed to be compatible and agnostic to the existing tensor
+frameworks. It provides a backend adapter interface that allows easy porting
+to other tensor-based, autograd-enabled frameworks.
+
+
 Free software
 -------------
 DGL is free software; you can redistribute it and/or modify it under the terms

python/dgl/__init__.py

@@ -30,6 +30,7 @@ from .subgraph import *
 from .traversal import *
 from .transform import *
 from .propagate import *
+from .random import *
 
 from ._deprecate.graph import DGLGraph as DGLGraphStale
 from ._deprecate.nodeflow import *

python/dgl/random.py

@@ -5,6 +5,8 @@ from ._ffi.function import _init_api
 from . import backend as F
 from . import ndarray as nd
 
+__all__ = ['seed']
+
 def seed(val):
     """Set the seed of randomized methods in DGL.