From fb436e8239c0be281b833c775df43f47409a69c8 Mon Sep 17 00:00:00 2001
From: ChenXin <will131@foxmail.com>
Date: Thu, 15 Aug 2019 17:06:38 +0800
Subject: [PATCH] update some docs of io modules

---
 fastNLP/io/data_loader/__init__.py |  4 +++
 fastNLP/io/dataset_loader.py       |  5 +++
 fastNLP/io/loader/__init__.py      | 50 ++++++++++++++++++------------
 fastNLP/io/pipe/__init__.py        |  7 +++--
 4 files changed, 43 insertions(+), 23 deletions(-)

diff --git a/fastNLP/io/data_loader/__init__.py b/fastNLP/io/data_loader/__init__.py
index 5d6b08b0..b3ca9021 100644
--- a/fastNLP/io/data_loader/__init__.py
+++ b/fastNLP/io/data_loader/__init__.py
@@ -1,4 +1,8 @@
 """
+.. warning::
+
+    本模块在 `0.5.0版本` 中被废弃，由 :mod:`~fastNLP.io.loader`  和 :mod:`~fastNLP.io.pipe` 模块替代。
+
 用于读数据集的模块, 可以读取文本分类、序列标注、Matching任务的数据集
 
 这些模块的具体介绍如下，您可以通过阅读 :doc:`教程</tutorials/tutorial_2_load_dataset>` 来进行了解。
diff --git a/fastNLP/io/dataset_loader.py b/fastNLP/io/dataset_loader.py
index 3e3ac575..e1e06ec9 100644
--- a/fastNLP/io/dataset_loader.py
+++ b/fastNLP/io/dataset_loader.py
@@ -1,4 +1,8 @@
 """
+.. warning::
+
+    本模块将在 `0.5.0版本` 中被废弃，由 :mod:`~fastNLP.io.loader`  和 :mod:`~fastNLP.io.pipe` 模块替代。
+
 dataset_loader模块实现了许多 DataSetLoader, 用于读取不同格式的数据, 并返回 `DataSet` ,
 得到的 :class:`~fastNLP.DataSet` 对象可以直接传入 :class:`~fastNLP.Trainer` 和 :class:`~fastNLP.Tester`, 用于模型的训练和测试。
 以SNLI数据集为例::
@@ -11,6 +15,7 @@ dataset_loader模块实现了许多 DataSetLoader, 用于读取不同格式的
     # ... do stuff
     
 为 fastNLP 提供 DataSetLoader 的开发者请参考 :class:`~fastNLP.io.DataSetLoader` 的介绍。
+
 """
 __all__ = [
     'CSVLoader',
diff --git a/fastNLP/io/loader/__init__.py b/fastNLP/io/loader/__init__.py
index 8c0d391c..5abef0eb 100644
--- a/fastNLP/io/loader/__init__.py
+++ b/fastNLP/io/loader/__init__.py
@@ -1,25 +1,35 @@
 """
 Loader用于读取数据，并将内容读取到 :class:`~fastNLP.DataSet` 或者 :class:`~fastNLP.io.DataBundle` 中。所有的Loader都支持以下的
-三个方法： __init__()，_load(), loads(). 其中__init__()用于申明读取参数，以及说明该Loader支持的数据格式，读取后Dataset中field
-; _load(path)方法传入一个文件路径读取单个文件，并返回DataSet; load(paths)用于读取文件夹下的文件，并返回DataBundle, load()方法
-支持以下三种类型的参数::
-
-    (0) 如果传入None，将尝试自动下载数据集并缓存。但不是所有的数据都可以直接下载。
-    (1) 如果传入的是一个文件path，则返回的DataBundle包含一个名为train的DataSet可以通过data_bundle.datasets['train']获取
-    (2) 传入的是一个文件夹目录，将读取的是这个文件夹下文件名中包含'train', 'test', 'dev'的文件，其它文件会被忽略。
-        假设某个目录下的文件为
-            -train.txt
-            -dev.txt
-            -test.txt
-            -other.txt
-        Loader().load('/path/to/dir')读取，返回的data_bundle中可以用data_bundle.datasets['train'], data_bundle.datasets['dev'],
-            data_bundle.datasets['test']获取对应的DataSet，其中other.txt的内容会被忽略。
-        假设某个目录下的文件为
-            -train.txt
-            -dev.txt
-        Loader().load('/path/to/dir')读取，返回的data_bundle中可以用data_bundle.datasets['train'], data_bundle.datasets['dev']获取
-            对应的DataSet。
-    (3) 传入一个dict，key为dataset的名称，value是该dataset的文件路径。
+三个方法： ``__init__`` ， ``_load`` , ``loads`` . 其中 ``__init__(...)`` 用于申明读取参数，以及说明该Loader支持的数据格式，
+读取后 :class:`~fastNLP.Dataset` 中的 `field` ; ``_load(path)`` 方法传入文件路径读取单个文件，并返回 :class:`~fastNLP.Dataset` ;
+``load(paths)`` 用于读取文件夹下的文件，并返回 :class:`~fastNLP.io.DataBundle` 类型的对象 , load()方法支持以下几种类型的参数:
+
+0.传入None
+    将尝试自动下载数据集并缓存。但不是所有的数据都可以直接下载。
+
+1.传入一个文件path
+    返回的 data_bundle 包含一个名为 `train` 的 dataset ,可以通过 data_bundle.datasets['train']获取
+
+2.传入一个文件夹目录
+    将读取的是这个文件夹下文件名中包含'train', 'test', 'dev'的文件，其它文件会被忽略。假设某个目录下的文件为::
+
+        -train.txt
+        -dev.txt
+        -test.txt
+        -other.txt
+
+    Loader().load('/path/to/dir')读取，返回的 data_bundle 中可以用 data_bundle.datasets['train'], data_bundle.datasets['dev'],
+    data_bundle.datasets['test'] 获取对应的DataSet，其中other.txt的内容会被忽略。假设某个目录下的文件为::
+
+        -train.txt
+        -dev.txt
+
+    Loader().load('/path/to/dir')读取，返回的 data_bundle 中可以用 data_bundle.datasets['train'],
+    data_bundle.datasets['dev'] 获取对应的DataSet。
+
+3.传入一个dict
+    key为 dataset 的名称，value 是该 dataset 的文件路径::
+
         paths = {'train':'/path/to/train', 'dev': '/path/to/dev', 'test':'/path/to/test'}
         Loader().load(paths)  # 返回的data_bundle可以通过以下的方式获取相应的DataSet, data_bundle.datasets['train'], data_bundle.datasets['dev'],
             data_bundle.datasets['test']
diff --git a/fastNLP/io/pipe/__init__.py b/fastNLP/io/pipe/__init__.py
index 4cec3ad5..6a5e6948 100644
--- a/fastNLP/io/pipe/__init__.py
+++ b/fastNLP/io/pipe/__init__.py
@@ -1,7 +1,8 @@
 """
-Pipe用于处理数据，所有的Pipe都包含一个process(DataBundle)方法，传入一个DataBundle对象, 在传入DataBundle上进行原位修改，并将其返回；
-process_from_file(paths)传入的文件路径，返回一个DataBundle。process(DataBundle)或者process_from_file(paths)的返回DataBundle
-中的DataSet一般都包含原文与转换为index的输入，以及转换为index的target；除了DataSet之外，还会包含将field转为index时所建立的词表。
+Pipe用于处理数据，所有的Pipe都包含一个 process(data_bundle) 方法，传入一个 :class:`~fastNLP.io.DataBundle` 类型的对象,
+在传入 data_bundle 上进行原位修改，并将其返回； process_from_file(paths) 传入的文件路径，返回一个 :class:`~fastNLP.io.DataBundle` 。
+process(data_bundle) 或者 process_from_file(paths)的返回 :class:`~fastNLP.io.DataBundle` 中的 :class:`~fastNLP.DataSet`
+ 一般都包含原文与转换为index的输入以及转换为index的target；除了 :class:`~fastNLP.DataSet` 之外，还会包含将field转为index时所建立的词表。
 
 """
 __all__ = [