Improve Documentation (#1374)

Author: sxjscience

.gitignore

@@ -115,8 +115,8 @@ docs/html
 
 # release
 scripts/*.zip
-docs/examples/*.zip
-docs/examples/*/*.ipynb
+docs/tutorials/*.zip
+docs/tutorials/*/*.ipynb
 
 conda
 

Makefile

@@ -19,7 +19,7 @@ ROOTDIR = $(CURDIR)
 MD2IPYNB = $(ROOTDIR)/docs/md2ipynb.py
 
 docs: docs_local
-	for f in $(shell find docs/examples -type f -name '*.md' -print) ; do \
+	for f in $(shell find docs/tutorials -type f -name '*.md' -print) ; do \
 		FILE=`echo $$f | sed 's/docs\///g'` ; \
 		DIR=`dirname $$FILE` ; \
 		BASENAME=`basename $$FILE` ; \
@@ -54,7 +54,7 @@ clean:
 	git clean -ff -d -x --exclude="$(ROOTDIR)/tests/data/*" --exclude="$(ROOTDIR)/conda/" --exclude="$(ROOTDIR)/.idea/"
 
 compile_notebooks:
-	for f in $(shell find docs/examples -type f -name '*.md' -print) ; do \
+	for f in $(shell find docs/tutorials -type f -name '*.md' -print) ; do \
 		DIR=$$(dirname $$f) ; \
 		BASENAME=$$(basename $$f) ; \
 		TARGETNAME=$${BASENAME%.md}.ipynb ; \
@@ -73,7 +73,7 @@ dist_scripts:
 	find * -type d -prune | grep -v 'tests\|__pycache__' | xargs -t -n 1 -I{} zip -r {}.zip {}
 
 dist_notebooks:
-	cd docs/examples && \
+	cd docs/tutorials && \
 	find * -type d -prune | grep -v 'tests\|__pycache__' | xargs -t -n 1 -I{} zip -r {}.zip {} -x "*.md" -x "__pycache__" -x "*.pyc" -x "*.txt" -x "*.log" -x "*.params" -x "*.npz" -x "*.json"
 
 distribute: dist_scripts dist_notebooks

README.md

@@ -1,3 +1,7 @@
+<h2 align="center">
+<a href="https://github.com/dmlc/gluon-nlp"><img src="https://raw.githubusercontent.com/dmlc/gluon-nlp/master/docs/_static/gluon-logo.svg" alt="GluonNLP Logo" width="500"/></a>
+</h2>
+
 <h2 align="center">
 GluonNLP: Your Choice of Deep Learning for NLP
 </h2>

docs/README.txt

@@ -1,3 +1,5 @@
-The documentation of gluonnlp is generated with recommonmark and sphinx.
+The documentation of GluonNLP is generated with recommonmark and sphinx.
 
 - pip install sphinx>=1.5.5 sphinx-gallery sphinx_rtd_theme matplotlib Image recommonmark
+
+For more details, refer to [website/configuration.rst](website/configuration.rst)

docs/api/attention.rst

@@ -0,0 +1,15 @@
+gluonnlp.attention_cell
+=======================
+
+GluonNLP Toolkit provides ways to implement the attention mechanism that is prevailing in NLP models.
+
+.. currentmodule:: gluonnlp.attention_cell
+
+Attention Mechanism
+-------------------
+
+.. automodule:: gluonnlp.attention_cell
+    :members:
+    :imported-members:
+    :special-members: __contains__, __getitem__, __setitem__
+

docs/api/data.rst

@@ -5,11 +5,39 @@ GluonNLP Toolkit provides tools for building efficient data pipelines for NLP ta
 
 .. currentmodule:: gluonnlp.data
 
+Tokenizers
+----------
+.. automodule:: gluonnlp.data.tokenizers
+    :members:
+    :imported-members:
+    :special-members: __contains__, __getitem__, __setitem__
 
-API Reference
--------------
-
-.. automodule:: gluonnlp.data
+Vocabulary
+----------
+.. automodule:: gluonnlp.data.vocab
     :members:
     :imported-members:
     :special-members: __contains__, __getitem__, __setitem__
+
+Batchify Function
+-----------------
+.. automodule:: gluonnlp.data.batchify
+    :members:
+
+Data Sampler
+------------
+.. automodule:: gluonnlp.data.sampler
+    :members:
+    :imported-members:
+
+Text Filtering
+--------------
+.. automodule:: gluonnlp.data.filtering
+    :members:
+    :imported-members:
+
+Data Loading
+------------
+.. automodule:: gluonnlp.data.loading
+    :members:
+    :imported-members:

docs/api/index.rst

@@ -2,9 +2,13 @@ API Documentation
 =================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    data
    embedding
    models
+   attention
+   layers
+   operators
+   sequence_sampler
    utils

docs/api/layers.rst

@@ -0,0 +1,15 @@
+gluonnlp.layers
+===============
+
+GluonNLP Toolkit provides some common layers that can help you build NLP models.
+
+.. currentmodule:: gluonnlp.layers
+
+Layers
+------
+
+.. automodule:: gluonnlp.layers
+    :members:
+    :imported-members:
+    :special-members: __contains__, __getitem__, __setitem__
+

docs/api/models.rst

@@ -2,14 +2,15 @@ gluonnlp.models
 ===============
 
 GluonNLP Toolkit supplies models for common NLP tasks with pre-trained weights. By default,
-all requested pre-trained weights are downloaded from public repo and stored in ~/.mxnet/models/.
+all requested pre-trained weights are downloaded from public repo and stored in `~/.gluonnlp/models/`.
 
 .. currentmodule:: gluonnlp.models
+.. autosummary::
 
-API Reference
--------------
-
+Models
+------
 .. automodule:: gluonnlp.models
     :members:
+    :no-inherited-members:
     :imported-members:
     :special-members: __contains__, __getitem__, __setitem__

docs/api/operators.rst

@@ -0,0 +1,15 @@
+gluonnlp.op
+===============
+
+GluonNLP Toolkit provides some functions that can help you build NLP architectures and training pipelines.
+
+.. currentmodule:: gluonnlp.op
+
+Layers
+------
+
+.. automodule:: gluonnlp.op
+    :members:
+    :imported-members:
+    :special-members: __contains__, __getitem__, __setitem__
+

docs/api/sequence_sampler.rst

@@ -0,0 +1,15 @@
+gluonnlp.sequence_sampler
+=========================
+
+GluonNLP Toolkit provides ways to sample from a sequence generator.
+
+.. currentmodule:: gluonnlp.sequence_sampler
+
+Sequence Sampler
+----------------
+
+.. automodule:: gluonnlp.sequence_sampler
+    :members:
+    :imported-members:
+    :special-members: __contains__, __getitem__, __setitem__
+

docs/conf.py

@@ -122,8 +122,8 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '**.ipynb_checkpoints', 'examples/*/*/**.rst', 'model_zoo/*/*/**.rst',
-                    'model_zoo/word_embeddings/tools/extern/*/**.md', 'examples/*/**.md', 
+exclude_patterns = ['_build', '**.ipynb_checkpoints', 'tutorials/*/*/**.rst', 'model_zoo/*/*/**.rst',
+                    'model_zoo/word_embeddings/tools/extern/*/**.md', 'tutorials/*/**.md',
                     'model_zoo/*/**.md', 'model_zoo/*/*/**.md', 'model_zoo/*/*/**.rst']
 
 # The reST default role (used for this markup: `text`) to use for all

docs/model_zoo.rst docs/examples.rst

@@ -1,13 +1,14 @@
-Model Zoo
----------
+Examples
+--------
 
 .. container:: cards
 
    .. card::
       :title: Benchmarking the Performance of NLP Backbones
       :link: model_zoo/benchmarks/index.html
 
-      Placeholder.
+      Benchmarking the performance of NLP models.
+      We released the benchmarking script that compares different NLP packages.
 
    .. card::
       :title: Conversion Scripts
@@ -19,35 +20,37 @@ Model Zoo
       :title: Datasets
       :link: model_zoo/datasets/index.html
 
-      Placeholder.
+      Example about the datasets supported by `nlp_data`
 
    .. card::
       :title: Generation
       :link: model_zoo/generation/index.html
 
-      Placeholder. 
+      Example about how to generate from a pretrained GPT-2 model with GluonNLP.
+      We provided the generation script and tried to compare different sampling methods.
 
    .. card::
       :title: Machine Translation
       :link: model_zoo/machine_translation/index.html
 
-      From "Hello" to "Bonjour".
+      Train machine translation model with GluonNLP.
 
    .. card::
       :title: Data Preprocessing Toolkit in GluonNLP
       :link: model_zoo/processing/index.html
 
-      Placeholder.
+      Example about the data processing toolkit (`nlp_process`) offered in GluonNLP.
 
    .. card::
       :title: Pretraining Model
       :link: model_zoo/pretraining/index.html
 
-      Placeholder.
+      Examples about pretraining your own backbones.
 
    .. card::
       :title: Question Answering Examples
       :link: model_zoo/question_answering/index.html
 
-      Placeholder.
+      Run SQuAD 1.1 and 2.0 finetuning with GluonNLP. You will know how to run the models with
+      mixed-precision training (AMP) and Horovod.
 

docs/index.rst

@@ -37,9 +37,9 @@ computes the cosine similarity between two words.
    </script>
 
 
-.. include:: model_zoo.rst
+.. include:: examples.rst
 
-And more in :doc:`tutorials <examples/index>`.
+And more in :doc:`tutorials <tutorials/index>`.
 
 
 .. include:: install.rst
@@ -50,18 +50,17 @@ About GluonNLP
 
 .. hint::
 
-   You can find our the doc for our master development branch `here <http://gluon-nlp.mxnet.io/master/index.html>`_.
+   You can find out the doc for our master development branch `here <http://nlp.gluon.ai/master/index.html>`_.
 
 GluonNLP provides implementations of the state-of-the-art (SOTA) deep learning
 models in NLP, and build blocks for text data pipelines and models.
 It is designed for engineers, researchers, and students to fast prototype
 research ideas and products based on these models. This toolkit offers five main features:
 
-1. Training scripts to reproduce SOTA results reported in research papers.
+1. Carefully designed APIs that greatly reduce the implementation complexity.
 2. Pre-trained models for common NLP tasks.
-3. Carefully designed APIs that greatly reduce the implementation complexity.
-4. Tutorials to help get started on new NLP tasks.
-5. Community support.
+3. Tutorials to help get started on new NLP tasks.
+4. Community support.
 
 This toolkit assumes that users have basic knowledge about deep learning and
 NLP. Otherwise, please refer to an introductory course such as
@@ -76,8 +75,8 @@ You may find the 60-min Gluon crash course linked from there especially helpful.
    :hidden:
    :maxdepth: 2
 
+   tutorials/index
    model_zoo/index
-   examples/index
    api/index
    website/index
    genindex