[Doc] main doc page update and contribute guide (dmlc#336)

* reorg the doc mainpage * contribute guide
ChenAris · Jan 4, 2019 · 6f9ae8d · 6f9ae8d
1 parent 24bbdb7
commit 6f9ae8d
Show file tree

Hide file tree

Showing 16 changed files with 309 additions and 61 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -0,0 +1,15 @@
+## Contributing to DGL
+
+Contribution is always welcomed. A good starting place is the roadmap issue, where
+you can find our current milestones. All contributions must go through pull requests
+and be reviewed by the committors. See our [contribution guide](https://docs.dgl.ai/contribute.html) for more details.
+
+Once your contribution is accepted and merged, congratulation, you are now an contributor to the DGL project.
+We will put your name in the list below and also on our [website](https://www.dgl.ai/ack).
+
+Contributors
+------------
+[Yizhi Liu](https://github.com/yzhliu)
+[Yifei Ma](https://github.com/yifeim)
+Hao Jin
+[Sheng Zha](https://github.com/szha)
diff --git a/README.md b/README.md
@@ -156,7 +156,7 @@ Check out the open source book [*Dive into Deep Learning*](http://en.diveintodee
 Please let us know if you encounter a bug or have any suggestions by [filing an issue](https://github.com/dmlc/dgl/issues).
 
 We welcome all contributions from bug fixes to new features and extensions.
-We expect all contributions discussed in the issue tracker and going through PRs.  Please refer to the PR guide.
+We expect all contributions discussed in the issue tracker and going through PRs.  Please refer to our [contribution guide](https://docs.dgl.ai/contribute.html).
 
 
 ## The Team

diff --git a/docs/README.md b/docs/README.md
@@ -1,6 +1,12 @@
 DGL document and tutorial folder
 ================================
 
+Requirements
+------------
+* sphinx
+* sphinx-gallery
+* Both pytorch and mxnet installed.
+
 Build documents
 ---------------
 First, clean up existing files:

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -211,4 +211,5 @@
     'gallery_dirs' : gallery_dirs,
     'within_subsection_order' : FileNameSortKey,
     'filename_pattern' : '.py',
+    'download_all_examples' : False,
 }
diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst
@@ -0,0 +1,136 @@
+Contribute to DGL
+=================
+
+Any contribution to DGL is welcome. This guide covers everything
+about how to contribute to DGL.
+
+General development process
+---------------------------
+
+A non-inclusive list of types of contribution is as follows:
+
+* New features and enhancements (`example <https://github.com/dmlc/dgl/pull/331>`__).
+* Bugfix (`example <https://github.com/dmlc/dgl/pull/247>`__).
+* Document improvement (`example <https://github.com/dmlc/dgl/pull/263>`__).
+* New models and examples (`example <https://github.com/dmlc/dgl/pull/279>`__).
+
+For features and bugfix, we recommend first raise an `issue <https://github.com/dmlc/dgl/issues>`__
+using the corresponding issue template, so that the change could be fully discussed with
+the community before implementation. For document improvement and new models, we suggest
+post a thread in our `discussion forum <https://discuss.dgl.ai>`__.
+
+Before development, please first read the following sections about coding styles and testing.
+All the changes need to be reviewed in the form of `pull request <https://github.com/dmlc/dgl/pulls>`__.
+Our `committors <https://github.com/orgs/dmlc/teams/dgl-team/members>`__
+(who have write permission on the repository) will review the codes and suggest the necessary
+changes. The PR could be merged once the reviewers approve the changes.
+
+Git setup (for developers)
+--------------------------
+
+First, fork the DGL github repository. Suppose the forked repo is ``https://github.com/username/dgl``.
+
+Clone your forked repository locally:
+
+.. code-block:: bash
+
+   git clone --recursive https://github.com/username/dgl.git
+
+
+Setup the upstream to the DGL official repository:
+
+.. code-block:: bash
+
+   git remote add upstream https://github.com/dmlc/dgl.git
+
+You could verify the remote setting by typing ``git remove -v``:
+
+.. code-block:: bash
+
+   origin  https://github.com/username/dgl.git (fetch)
+   origin  https://github.com/username/dgl.git (push)
+   upstream        https://github.com/dmlc/dgl.git (fetch)
+   upstream        https://github.com/dmlc/dgl.git (push)
+
+During developing, we suggest work on another branch than the master.
+
+.. code-block:: bash
+
+   git branch working-branch
+   git checkout working-branch
+
+Once the changes are done, `create a pull request <https://help.github.com/articles/creating-a-pull-request/>`__
+so we could review your codes.
+
+Once the pull request is merged, update your forked repository and delete your working branch:
+
+.. code-block:: bash
+
+   git checkout master
+   git pull upstream master
+   git push origin master  # update your forked repo
+   git branch -D working-branch  # the local branch could be deleted
+
+Coding styles
+-------------
+
+For python codes, we generally follow the `PEP8 style guide <https://www.python.org/dev/peps/pep-0008/>`__.
+The python comments follow `NumPy style python docstrings <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`__.
+
+For C++ codes, we generally follow the `Google C++ style guide <https://google.github.io/styleguide/cppguide.html>`__.
+The C++ comments should be `Doxygen compatible <http://www.doxygen.nl/manual/docblocks.html#cppblock>`__.
+
+Coding styles check is mandatory for every pull requests. To ease the development, please check it
+locally first (require cpplint and pylint to be installed first):
+
+.. code-block:: bash
+
+   bash tests/scripts/task_lint.sh
+
+The python code style configure file is ``tests/scripts/pylintrc``. We tweak it a little bit from
+the standard. For example, following variable names are accepted:
+
+* ``i,j,k``: for loop variables
+* ``u,v``: for representing nodes
+* ``e``: for representing edges
+* ``g``: for representing graph
+* ``fn``: for representing functions
+* ``n,m``: for representing sizes
+* ``w,x,y``: for representing weight, input, output tensors
+* ``_``: for unused variables
+
+Building and Testing
+--------------------
+
+To build DGL locally, follow the steps described in :ref:`Install from source <install-from-source>`.
+However, to ease the development, we suggest NOT install DGL but directly working in the source tree.
+To achieve this, export following environment variables:
+
+.. code-block:: bash
+
+   export DGL_HOME=/path/to/your/dgl/clone
+   export DGL_LIBRARY_PATH=$DGL_HOME/build
+   export PYTHONPATH=$PYTHONPATH:$DGL_HOME/python
+
+You could test the build by running the following command and see the path of your local clone.
+
+.. code-block:: bash
+
+   python -c 'import dgl; print(dgl.__path__)'
+
+TBD by Quan about how to run and write unittests.
+
+Building documents
+------------------
+
+If the change is about document improvement, we suggest build the document and render it locally
+before pull request. See instructions `here <https://github.com/dmlc/dgl/tree/master/docs>`__.
+
+Data hosting
+------------
+
+If the change is about new models or applications, it is very common to have some data files. Data
+files are not allowed to be uploaded to our repository. Instead, they should be hosted on the
+cloud storage service (e.g. dropbox, Amazon S3) and downloaded on-the-fly. See our :ref:`dataset APIs <apidata>`
+for more details. All the dataset of current DGL models are hosted on Amazon S3. If you want your
+dataset to be hosted as well, please post in our `discussion forum <https://discuss.dgl.ai>`__.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -37,36 +37,113 @@ frameworks. It provides a backend adapter interface that allows easy porting
 to other tensor-based, autograd-enabled frameworks. Currently, our prototype
 works with MXNet/Gluon and PyTorch.
 
-Free software
--------------
-DGL is free software; you can redistribute it and/or modify it under the terms
-of the Apache License 2.0. We welcome contributions.
-Join us on `GitHub <https://github.com/dmlc/dgl>`_ and check out our `contribution guidelines <https://github.com/dmlc/dgl/blob/master/CONTRIBUTING.md>`_.
-
-History
--------
-Prototype of DGL started in early Spring, 2018, at NYU Shanghai by Prof. Zheng
-Zhang and Quan Gan. Serious development began when Minjie, Lingfan and Prof
-Jinyang Li from NYU's system group joined, flanked by a team of student
-volunteers at NYU Shanghai, Fudan and other universities (Yu, Zihao, Murphy,
-Allen, Qipeng, Qi, Hao), as well as early adopters at the CILVR lab (Jake
-Zhao). Development accelerated when AWS MXNet Science team joined force, with
-Da Zheng, Alex Smola, Haibin Lin, Chao Ma and a number of others. For full
-credit, see `here <https://www.dgl.ai/ack>`_.
+Get Started
+-----------
 
 .. toctree::
    :maxdepth: 1
    :caption: Get Started
+   :hidden:
    :glob:
 
    install/index
 
+Follow the :doc:`instructions<install/index>` to install DGL. The :doc:`DGL at a glance<tutorials/basics/1_first>`
+is the most common place to get started with. Each tutorial is accompanied with a runnable
+python script and jupyter notebook that can be downloaded.
+
+.. ================================================================================================
+   (start) MANUALLY INCLUDE THE GENERATED TUTORIALS/BASIC/INDEX.RST HERE TO EMBED THE EXAMPLES
+   ================================================================================================
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer">
+
+.. only:: html
+
+    .. figure:: /tutorials/basics/images/thumb/sphx_glr_1_first_thumb.png
+
+        :ref:`sphx_glr_tutorials_basics_1_first.py`
+
+.. raw:: html
+
+    </div>
+
+
 .. toctree::
-   :maxdepth: 2
-   :caption: Tutorials
+   :hidden:
+
+   /tutorials/basics/1_first
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer">
+
+.. only:: html
+
+    .. figure:: /tutorials/basics/images/thumb/sphx_glr_2_basics_thumb.png
+
+        :ref:`sphx_glr_tutorials_basics_2_basics.py`
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /tutorials/basics/2_basics
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer">
+
+.. only:: html
+
+    .. figure:: /tutorials/basics/images/thumb/sphx_glr_3_pagerank_thumb.png
+
+        :ref:`sphx_glr_tutorials_basics_3_pagerank.py`
+
+.. raw:: html
+
+    </div>
+
+.. toctree::
+   :hidden:
+
+   /tutorials/basics/3_pagerank
+
+.. raw:: html
+
+    <div style='clear:both'></div>
+
+.. ================================================================================================
+   (end) MANUALLY INCLUDE THE GENERATED TUTORIALS/BASIC/INDEX.RST HERE TO EMBED THE EXAMPLES
+   ================================================================================================
+
+Learning DGL through examples
+-----------------------------
+
+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
+  popular **GNN models** on one input graph.
+* :ref:`Dealing with many small graphs <tutorials2-index>`: Learn how to **batch** many
+  graph samples for max efficiency.
+* :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.
+
+Or go through all of them :doc:`here <tutorials/models/index>`.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Model Tutorials
+   :hidden:
    :glob:
 
-   tutorials/basics/index
    tutorials/models/index
 
 .. toctree::
@@ -78,10 +155,35 @@ credit, see `here <https://www.dgl.ai/ack>`_.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Notes
+   :hidden:
    :glob:
 
+   contribute
    faq
    env_var
+   resources
+
+Free software
+-------------
+DGL is free software; you can redistribute it and/or modify it under the terms
+of the Apache License 2.0. We welcome contributions.
+Join us on `GitHub <https://github.com/dmlc/dgl>`_ and check out our
+`contribution guidelines <https://github.com/dmlc/dgl/blob/master/CONTRIBUTING.md>`_.
+
+History
+-------
+Prototype of DGL started in early Spring, 2018, at NYU Shanghai by Prof. `Zheng
+Zhang <https://shanghai.nyu.edu/academics/faculty/directory/zheng-zhang>`_ and
+Quan Gan. Serious development began when `Minjie
+<https://jermainewang.github.io/>`_, `Lingfan <https://cs.nyu.edu/~lingfan/>`_
+and Prof. `Jinyang Li <http://www.news.cs.nyu.edu/~jinyang/>`_ from NYU's
+system group joined, flanked by a team of student volunteers at NYU Shanghai,
+Fudan and other universities (Yu, Zihao, Murphy, Allen, Qipeng, Qi, Hao), as
+well as early adopters at the CILVR lab (Jake Zhao). Development accelerated
+when AWS MXNet Science team joined force, with Da Zheng, Alex Smola, Haibin
+Lin, Chao Ma and a number of others. For full credit, see `here
+<https://www.dgl.ai/ack>`_.
 
 Index
 -----

diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst
@@ -68,6 +68,8 @@ The backend is controlled by ``DGLBACKEND`` environment variable, which defaults
 | numpy   | NumPy   | Does not support gradient computation            |
 +---------+---------+--------------------------------------------------+
 
+.. _install-from-source:
+
 Install from source
 -------------------
 First, download the source files from GitHub:

diff --git a/docs/source/resources.rst b/docs/source/resources.rst
@@ -0,0 +1,6 @@
+Resources
+=========
+* If you are new to deep learning, `Dive into Deep Learning <http://diveintodeeplearning.org>`__
+  is a nice book to start with.
+* `Pytorch tutorials <https://pytorch.org/tutorials/>`__
+* Thomas Kipf's `blog on Graph Convolutional Networks <https://tkipf.github.io/graph-convolutional-networks/>`__