refine reader doc

Author: sneaxiy

doc/fluid/user_guides/howto/prepare_data/feeding_data.rst

@@ -1,8 +1,8 @@
 .. _user_guide_use_numpy_array_as_train_data:
 
-###########################
-使用Numpy Array作为训练数据
-###########################
+#################################
+使用同步Feed方式读取Batch级Reader数据
+#################################
 
 PaddlePaddle Fluid支持使用 :code:`fluid.layers.data()` 配置数据层；
 再使用 Numpy Array 或者直接使用Python创建C++的
@@ -84,7 +84,7 @@ PaddlePaddle Fluid支持使用 :code:`fluid.layers.data()` 配置数据层；
    exe.run(feed={
      "sentence": create_lod_tensor(
        data=numpy.array([1, 3, 4, 5, 3, 6, 8], dtype='int64').reshape(-1, 1),
-       lod=[4, 1, 2],
+       lod=[[4, 1, 2]],
        place=fluid.CPUPlace()
      )
    })

doc/fluid/user_guides/howto/prepare_data/index.rst

@@ -4,52 +4,70 @@
 准备数据
 ########
 
-PaddlePaddle Fluid支持两种传入数据的方式:
+使用PaddlePaddle Fluid准备数据分为两个步骤：
 
-1. Python Reader同步方式：用户需要使用 :code:`fluid.layers.data`
+- 自定义Reader生成训练/预测数据，生成的数据类型可以为Numpy Array或LoDTensor。根据Reader返回的数据形式的不同，可分为Batch级的Reader（每次返回一个batch的数据）和样本级的Reader（每次返回单个样本的数据）。
+
+- 使用同步Feed方式或异步py_reader接口方式将数据送入网络进行训练/预测。
+
+同步Feed方式和异步py_reader接口方式的比较
+######################################
+
+同步Feed方式和异步py_reader接口方式的不同体现于：
+
+1. 同步Feed方式：用户需使用 :code:`fluid.layers.data`
 配置数据输入层，并在 :code:`fluid.Executor` 或 :code:`fluid.ParallelExecutor`
-中，使用 :code:`executor.run(feed=...)` 传入训练数据。
+中使用 :code:`executor.run(feed=...)` 传入训练数据。数据准备和模型训练/预测的过程是同步进行的，
+效率较低。
 
-2. py_reader接口异步方式：用户需要先使用 :code:`fluid.layers.py_reader` 配置数据输入层，然后使用
+2. 异步py_reader接口方式：用户需要先使用 :code:`fluid.layers.py_reader` 配置数据输入层，然后使用
 :code:`py_reader` 的 :code:`decorate_paddle_reader` 或 :code:`decorate_tensor_provider`
-方法配置数据源，再通过 :code:`fluid.layers.read_file` 读取数据。
+方法配置数据源，再通过 :code:`fluid.layers.read_file` 读取数据。数据传入与模型训练/预测过程是异步进行的，
+效率较高。
 
 
 这两种准备数据方法的比较如下:
 
 ========  =================================   =====================================
-对比项            Python Reader同步方式                py_reader接口异步方式
+对比项            同步Feed方式                          异步py_reader接口方式
 ========  =================================   =====================================
 API接口     :code:`executor.run(feed=...)`       :code:`fluid.layers.py_reader`
-数据格式              Numpy Array                   Numpy Array或LoDTensor
+数据格式         Numpy Array或LoDTensor               Numpy Array或LoDTensor
 数据增强          Python端使用其他库完成                  Python端使用其他库完成
 速度                     慢                                   快
 推荐用途                调试模型                              工业训练
 ========  =================================   =====================================
 
-Python Reader同步方式
-#####################
+读取Batch级Reader数据
+#######################
 
-Fluid提供Python Reader方式传入数据。
-Python Reader是纯的Python端接口，数据传入与模型训练/预测过程是同步的。用户可通过Numpy Array传入
-数据，具体请参考:
+若使用同步Feed方式送入数据，具体请参见:
 
 .. toctree::
    :maxdepth: 1
 
    feeding_data.rst
 
-Python Reader支持组batch、shuffle等高级功能，具体请参考：
+若使用异步py_reader接口方式送入数据，请调用py_reader的 :code:`decorate_tensor_provider` 接口完成，具体方式请参见:
 
 .. toctree::
    :maxdepth: 1
 
-   reader_cn.md
+   use_py_reader.rst
 
-py_reader接口异步方式
+读取样本级Reader数据
 #####################
 
-Fluid提供PyReader异步数据传入方式，数据传入与模型训练/预测过程是异步的，效率较高。具体请参考：
+若自定义的Reader每次返回单个样本的数据，用户需通过以下步骤完成数据送入：
+
+- 调用Fluid提供的Reader相关接口完成组batch和部分的数据预处理功能，具体请参见：
+
+.. toctree::
+   :maxdepth: 1
+
+   reader_cn.md
+
+- 若使用同步Feed方式送入数据，请使用DataFeeder接口将Reader数据转换为LoDTensor格式后送入网络，具体请参见 :ref:`cn_api_fluid_DataFeeder` 。若使用异步py_reader接口方式送入数据，请调用 :code:`decorate_paddle_reader` 接口完成，具体请参见：
 
 .. toctree::
    :maxdepth: 1

doc/fluid/user_guides/howto/prepare_data/reader_cn.md

@@ -1,7 +1,7 @@
 # Python Reader
 在模型训练和预测阶段，PaddlePaddle程序需要读取训练或预测数据。为了帮助用户编写数据读取的代码，我们提供了如下接口：
 
-- *reader*: 用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个数据项。
+- *reader*: 样本级的reader，用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个样本数据项。
 - *reader creator*: 接受一个或多个reader作为参数、返回一个新reader的函数。
 - *reader decorator*: 一个函数，接受一个或多个reader，并返回一个reader。
 - *batch reader*: 用于读取数据的函数，数据可来自于文件、网络、随机数生成器等，函数每次返回一个batch大小的数据项。
@@ -185,15 +185,4 @@ def image_reader_creator(image_path, label_path, n):
 
 # images_reader_creator创建一个reader
 reader = image_reader_creator("/path/to/image_file", "/path/to/label_file", 1024)
-paddle.train(paddle.batch(reader, 128), {"image":0, "label":1}, ...)
-```
-
-### `paddle.train`实现原理
-实现`paddle.train`的示例如下：
-
-```python
-def train(batch_reader, mapping, batch_size, total_pass):
-    for pass_idx in range(total_pass):
-        for mini_batch in batch_reader(): # this loop will never end in online learning.
-            do_forward_backward(mini_batch, mapping)
 ```