fastnlp · WillQvQ · May 22, 2019 · Feb 6, 2019 · Feb 6, 2019 · Feb 9, 2019
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -0,0 +1,7 @@
+include requirements.txt
+include LICENSE
+include README.md
+prune test/
+prune reproduction/
+prune fastNLP/api
+prune fastNLP/automl
diff --git a/README.md b/README.md
@@ -6,87 +6,108 @@
 ![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)
 [![Documentation Status](https://readthedocs.org/projects/fastnlp/badge/?version=latest)](http://fastnlp.readthedocs.io/?badge=latest)
 
-FastNLP is a modular Natural Language Processing system based on PyTorch, built for fast development of NLP models. 
+fastNLP 是一款轻量级的 NLP 处理套件。你既可以使用它快速地完成一个命名实体识别（NER）、中文分词或文本分类任务； 也可以使用他构建许多复杂的网络模型，进行科研。它具有如下的特性：
+
+- 统一的Tabular式数据容器，让数据预处理过程简洁明了。内置多种数据集的DataSet Loader，省去预处理代码。
+- 各种方便的NLP工具，例如预处理embedding加载; 中间数据cache等;
+- 详尽的中文文档以供查阅；
+- 提供诸多高级模块，例如Variational LSTM, Transformer, CRF等;
+- 封装CNNText，Biaffine等模型可供直接使用;
+- 便捷且具有扩展性的训练器; 提供多种内置callback函数，方便实验记录、异常捕获等。
+
+
+## 安装指南
+
+fastNLP 依赖如下包:
+
++ numpy
++ torch>=0.4.0
++ tqdm
++ nltk
+
+其中torch的安装可能与操作系统及 CUDA 的版本相关，请参见 PyTorch 官网 。 
+在依赖包安装完成的情况，您可以在命令行执行如下指令完成安装
+
+```shell
+pip install fastNLP
+```
+
+
+## 内置组件
+
+大部分用于的 NLP 任务神经网络都可以看做由编码（encoder）、聚合（aggregator）、解码（decoder）三种模块组成。
+
+
+![](./docs/source/figures/text_classification.png)
+
+fastNLP 在 modules 模块中内置了三种模块的诸多组件，可以帮助用户快速搭建自己所需的网络。 三种模块的功能和常见组件如下:
 
-A deep learning NLP model is the composition of three types of modules:
 <table>
 <tr>
-    <td><b> module type </b></td>
-    <td><b> functionality </b></td>
-    <td><b> example </b></td>
+    <td><b> 类型 </b></td>
+    <td><b> 功能 </b></td>
+    <td><b> 例子 </b></td>
 </tr>
 <tr>
     <td> encoder </td>
-    <td> encode the input into some abstract representation </td>
+    <td> 将输入编码为具有具 有表示能力的向量 </td>
     <td> embedding, RNN, CNN, transformer
 </tr>
 <tr>
     <td> aggregator </td>
-    <td> aggregate and reduce information </td>
+    <td> 从多个向量中聚合信息 </td>
     <td> self-attention, max-pooling </td>
 </tr>
 <tr>
     <td> decoder </td>
-    <td> decode the representation into the output </td>
+    <td> 将具有某种表示意义的 向量解码为需要的输出 形式 </td>
     <td> MLP, CRF </td>
 </tr>
 </table>
 
-For example:
-
-![](docs/source/figures/text_classification.png)
-
-## Requirements
-
-- Python>=3.6
-- numpy>=1.14.2
-- torch>=0.4.0
-- tensorboardX
-- tqdm>=4.28.1
 
+## 完整模型
+fastNLP 为不同的 NLP 任务实现了许多完整的模型，它们都经过了训练和测试。
 
-## Resources
+你可以在以下两个地方查看相关信息
+- [介绍](reproduction/)
+- [源码](fastNLP/models/)
 
-- [Tutorials](https://github.com/fastnlp/fastNLP/tree/master/tutorials)
-- [Documentation](https://fastnlp.readthedocs.io/en/latest/)
-- [Source Code](https://github.com/fastnlp/fastNLP)
-
-
-## Installation
-Run the following commands to install fastNLP package.
-```shell
-pip install fastNLP
-```
+## 项目结构
 
+![](./docs/source/figures/workflow.png)
 
-## Project Structure
+fastNLP的大致工作流程如上图所示，而项目结构如下：
 
 <table>
 <tr>
     <td><b> fastNLP </b></td>
-    <td> an open-source NLP library </td>
-</tr>
-<tr>
-    <td><b> fastNLP.api </b></td>
-    <td> APIs for end-to-end prediction </td>
+    <td> 开源的自然语言处理库 </td>
 </tr>
 <tr>
     <td><b> fastNLP.core </b></td>
-    <td> data representation & train/test procedure </td>
+    <td> 实现了核心功能，包括数据处理组件、训练器、测速器等 </td>
 </tr>
 <tr>
     <td><b> fastNLP.models </b></td>
-    <td> a collection of NLP models </td>
+    <td> 实现了一些完整的神经网络模型 </td>
 </tr>
 <tr>
     <td><b> fastNLP.modules </b></td>
-    <td> a collection of PyTorch sub-models/components/wheels </td>
+    <td> 实现了用于搭建神经网络模型的诸多组件 </td>
 </tr>
 <tr>
     <td><b> fastNLP.io </b></td>
-    <td> readers & savers </td>
+    <td> 实现了读写功能，包括数据读入，模型读写等 </td>
 </tr>
 </table>
 
+## 参考资源
+
+- [教程](https://github.com/fastnlp/fastNLP/tree/master/tutorials)
+- [文档](https://fastnlp.readthedocs.io/en/latest/)
+- [源码](https://github.com/fastnlp/fastNLP)
+
+
 
 *In memory of @FengZiYjun.  May his soul rest in peace. We will miss you very very much!*
diff --git a/docs/Makefile b/docs/Makefile
@@ -3,6 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
+SPHINXAPIDOC  = sphinx-apidoc
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = fastNLP
 SOURCEDIR     = source
@@ -12,6 +13,12 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+apidoc:
+	$(SPHINXAPIDOC) -efM -o source ../$(SPHINXPROJ)
+
+server:
+	cd build/html && python -m http.server
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -14,6 +14,7 @@
 #
 import os
 import sys
+
 sys.path.insert(0, os.path.abspath('../../'))
 
 # -- Project information -----------------------------------------------------
@@ -23,10 +24,9 @@
 author = 'xpqiu'
 
 # The short X.Y version
-version = '0.2'
+version = '0.4'
 # The full version, including alpha/beta/rc tags
-release = '0.2'
-
+release = '0.4'
 
 # -- General configuration ---------------------------------------------------
 
@@ -42,9 +42,15 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
     'sphinx.ext.mathjax',
-
+    'sphinx.ext.todo'
 ]
 
+autodoc_default_options = {
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -62,17 +68,16 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "zh_CN"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = []
+exclude_patterns = ['modules.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -84,7 +89,10 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'collapse_navigation': False,
+    'titles_only': True
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -107,22 +115,21 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'fastNLPdoc'
 
-
 # -- Options for LaTeX output ------------------------------------------------
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
+    
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
+    
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
+    
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -136,7 +143,6 @@
      'xpqiu', 'manual'),
 ]
 
-
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
@@ -146,7 +152,6 @@
      [author], 1)
 ]
 
-
 # -- Options for Texinfo output ----------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
@@ -159,4 +164,14 @@
 ]
 
 
-# -- Extension configuration -------------------------------------------------
+# -- Extension configuration -------------------------------------------------
+def maybe_skip_member(app, what, name, obj, skip, options):
+    if name.startswith("_"):
+        return True
+    if obj.__doc__ is None:
+        return True
+    return False
+
+
+def setup(app):
+    app.connect('autodoc-skip-member', maybe_skip_member)
diff --git a/docs/source/fastNLP.api.rst b/docs/source/fastNLP.api.rst
diff --git a/docs/source/fastNLP.core.batch.rst b/docs/source/fastNLP.core.batch.rst
@@ -0,0 +1,7 @@
+fastNLP.core.batch
+==================
+
+.. automodule:: fastNLP.core.batch
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/fastNLP.core.callback.rst b/docs/source/fastNLP.core.callback.rst
@@ -0,0 +1,7 @@
+fastNLP.core.callback
+=====================
+
+.. automodule:: fastNLP.core.callback
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/fastNLP.core.const.rst b/docs/source/fastNLP.core.const.rst
@@ -0,0 +1,7 @@
+fastNLP.core.const
+==================
+
+.. automodule:: fastNLP.core.const
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/fastNLP.core.dataset.rst b/docs/source/fastNLP.core.dataset.rst
@@ -0,0 +1,7 @@
+fastNLP.core.dataset
+====================
+
+.. automodule:: fastNLP.core.dataset
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/fastNLP.core.field.rst b/docs/source/fastNLP.core.field.rst
@@ -0,0 +1,7 @@
+fastNLP.core.field
+==================
+
+.. automodule:: fastNLP.core.field
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/fastNLP.core.instance.rst b/docs/source/fastNLP.core.instance.rst
@@ -0,0 +1,7 @@
+fastNLP.core.instance
+=====================
+
+.. automodule:: fastNLP.core.instance
+    :members:
+    :undoc-members:
+    :show-inheritance: