refine dataloder doc. test=develop

doc/fluid/api_cn/io_cn.rst

@@ -10,13 +10,16 @@ fluid.io
     :maxdepth: 1
 
     io_cn/batch_cn.rst
+    io_cn/BatchSampler_cn.rst
     io_cn/buffered_cn.rst
     io_cn/cache_cn.rst
     io_cn/chain_cn.rst
     io_cn/compose_cn.rst
     io_cn/ComposeNotAligned_cn.rst
     io_cn/DataLoader_cn.rst  
+    io_cn/Dataset_cn.rst
     io_cn/firstn_cn.rst
+    io_cn/Flowers_cn.rst
     io_cn/get_program_parameter_cn.rst
     io_cn/get_program_persistable_vars_cn.rst
     io_cn/load_cn.rst
@@ -25,6 +28,7 @@ fluid.io
     io_cn/load_persistables_cn.rst
     io_cn/load_program_state_cn.rst
     io_cn/load_vars_cn.rst
+    io_cn/MNIST_cn.rst
     io_cn/map_readers_cn.rst
     io_cn/multiprocess_reader_cn.rst
     io_cn/PyReader_cn.rst

doc/fluid/api_cn/io_cn/BatchSampler_cn.rst

+.. _cn_api_fluid_io_BatchSampler:
+
+BatchSampler
+-------------------------------
+
+.. py:class:: paddle.fluid.io.BatchSampler(dataset=None, indices=None, shuffle=False, batch_size=1, drop_last=False)
+
+``fluid.io.DataLoader`` 使用的批次索引采样器，其可以迭代返回mini-batch的索引列表(长度为 ``batch_size`` ，内容为样本索引)。
+``fluid.io.DataLoader`` 的 ``batch_sampler`` 参数必须为 ``BatchSampler`` 及其子类实例。 ``BatchSampler`` 子类须实现如下两个方法：
+
+``__iter__`` : 迭代返回mini-batch索引列表。
+
+``__len__`` : 每个epoch中的mini-batch个数。
+
+参数:
+    - **dataset** (Dataset) - ``fluid.io.Dataset`` 实例或者实现了 ``__len__`` 接口的python对象，用于生成 ``dataset`` 长度范围的索引。默认值为None。
+    - **indices** (list|tuple) - 用于迭代的下标，``dataset`` 的替代参数， ``dataset`` 和 ``indices`` 必须设置其中之一。默认值为None。
+    - **shuffle** (bool) - 迭代返回索引之前是否对索引打乱顺序。默认值为False。
+    - **batch_size** (int) - 每mini-batch中的索引下标个数。默认值为1。
+    - **drop_last** (int) - 是否丢弃因数据集样本数不能被 ``batch_size`` 整除而产生的最后一个不完成的mini-batch索引。默认值为False。
+
+返回：迭代索引列表的迭代器
+
+返回类型: BatchSampler
+
+**代码示例**
+
+.. code-block:: python
+
+    from paddle.fluid.io import BatchSampler, MNIST
+
+    # init with indices
+    bs = BatchSampler(indices=list(range(1000)),
+                      shuffle=True,
+                      batch_size=8,
+                      drop_last=True)
+
+    for batch_indices in bs:
+        print(batch_indices)
+
+    # init with dataset
+    bs = BatchSampler(dataset=MNIST(mode='test')),
+                      shuffle=False,
+                      batch_size=16,
+                      drop_last=False)
+
+    for batch_indices in bs:
+        print(batch_indices)

doc/fluid/api_cn/io_cn/DataLoader_cn.rst

@@ -3,7 +3,139 @@
 DataLoader
 -------------------------------
 
-.. py:class:: paddle.fluid.io.DataLoader
+.. py:class:: paddle.fluid.io.DataLoader(dataset, feed_list=None, places=None, return_list=False, batch_sampler=None, batch_size=1, shuffle=False, drop_last=False, collate_fn=None, num_workers=0, use_buffer_reader=True, use_shared_memory=False, timeout=0, worker_init_fn=None)
+
+DataLoader返回一个迭代器，该迭代器根据 ``batch_sampler`` 给定的顺序迭代一次给定的 ``dataset``
+
+DataLoader支持单进程和多进程的数据加载方式，当 ``num_workers`` 大于0时，将使用多进程方式异步加载数据。
+
+DataLoader当前仅支持 ``map-style`` 的数据集(可通过下标索引样本)， ``map-style`` 的数据集请参考 ``fluid.io.Dataset`` 。
+
+``batch_sampler`` 请参考 ``fluid.io.BatchSampler``
+
+参数:
+    - **dataset** (Dataset) - DataLoader从此参数给定数据集中加载数据，此参数必须是 ``fluid.io.Dataset`` 的一个子类实例。
+    - **feed_list** (list(Variable)|tuple(Variable)) - feed变量列表，由 ``fluid.layers.data()`` 创建。当 ``return_list`` 为False时，此参数必须设置。默认值为None。
+    - **places** (list(Place)|tuple(Place)) - 数据需要放置到的Place列表。在静态图和动态图模式中，此参数均必须设置。在动态图模式中，此参数列表长度必须是1。默认值为None。
+    - **return_list** (bool) - 每个设备上的数据是否以list形式返回。若return_list = False，每个设备上的返回数据均是str -> LoDTensor的映射表，其中映射表的key是每个输入变量的名称。若return_list = True，则每个设备上的返回数据均是list(LoDTensor)。在动态图模式下，此参数必须为True。默认值为False。
+    - **batch_sampler** (BatchSampler) - ``fluid.io.BatchSampler`` 或其子类的实例，DataLoader通过 ``batch_sampler`` 产生的mini-batch索引列表来 ``dataset`` 中索引样本并组成mini-batch。默认值为None。
+    - **batch_size** (int) - 每mini-batch中样本个数，为 ``batch_sampler`` 的替代参数，若 ``batch_sampler`` 未设置，会根据 ``batch_size`` ``shuffle`` ``drop_last`` 创建一个 ``fluid.io.BatchSampler`` 。默认值为1。
+    - **shuffle** (bool) - 生成mini-batch索引列表时是否对索引打乱顺序，为 ``batch_sampler`` 的替代参数，若 ``batch_sampler`` 未设置，会根据 ``batch_size`` ``shuffle`` ``drop_last`` 创建一个 ``fluid.io.BatchSampler`` 。默认值为False。
+    - **drop_last** (bool) - 是否丢弃因数据集样本数不能被 ``batch_size`` 整除而产生的最后一个不完成的mini-batch，为 ``batch_sampler`` 的替代参数，若 ``batch_sampler`` 未设置，会根据 ``batch_size`` ``shuffle`` ``drop_last`` 创建一个 ``fluid.io.BatchSampler`` 。默认值为False。
+    - **collate_fn** (callable) - 通过此参数指定如果将样本列表组合为mini-batch数据，当 ``collate_fn`` 为None时，默认为将样本个字段在第0维上堆叠(同 ``np.stack(..., axis=0)`` )为mini-batch的数据。默认值为None。
+    - **num_workers** (int) - 用于加载数据的子进程个数，若为0即为不开启子进程，在主进程中进行数据加载。默认值为0。
+    - **use_buffer_reader** (bool) - 是否使用缓存读取器 。若 ``use_buffer_reader`` 为True，DataLoader会异步地预读取下一个mini-batch的数据，可加速数据读取过程，但同时会占用少量的CPU/GPU存储，即一个batch输入数据的存储空间。默认值为True。
+    - **use_shared_memory** (bool) - 是否使用共享内存来提升子进程将数据放入进程间队列的速度，该参数尽在多进程模式下有效(即 ``num_workers > 0`` )，请确认机器上有足够的共享内存空间(如Linux系统下 ``/dev/shm/`` 目录空间大小)再设置此参数。默认为False。
+    - **timeout** (int) - 从子进程输出队列获取mini-batch数据的超时时间。默认值为0。
+    - **worker_init_fn** (callable) - 子进程初始化函数，此函数会被子进程初始化时被调用，并传递 ``worker id`` 作为参数。默认值为None。
+
+返回：迭代 ``dataset`` 数据的迭代器
+
+返回类型: DataLoader
+
+**代码示例**
+
+.. code-block:: python
+
+    import numpy as np
+    import paddle.fluid as fluid
+    from paddle.fluid.io import Dataset, MnistDataset, BatchSampler, DataLoader
+
+    BATCH_NUM = 20
+    BATCH_SIZE = 16
+    EPOCH_NUM = 4
+
+    IMAGE_SIZE = 784
+    CLASS_NUM = 10
+
+    USE_GPU = True # whether use GPU to run model
+
+    # define a random dataset
+    class RandomDataset(Dataset):
+        def __init__(self, num_samples):
+            self.num_samples = num_samples
+
+        def __getitem__(self, idx):
+            image = np.random.random([IMAGE_SIZE]).astype('float32')
+            label = np.random.randint(0, CLASS_NUM - 1, (1, )).astype('int64')
+            return image, label
+
+        def __len__(self):
+            return self.num_samples
+
+    # get places
+    places = fluid.cuda_places() if USE_GPU else fluid.cpu_places()
+
+    # -------------------- static graph ---------------------
+
+    def simple_net(image, label):
+        fc_tmp = fluid.layers.fc(image, size=CLASS_NUM, act='softmax')
+        cross_entropy = fluid.layers.softmax_with_cross_entropy(image, label)
+        loss = fluid.layers.reduce_mean(cross_entropy)
+        sgd = fluid.optimizer.SGD(learning_rate=1e-3)
+        sgd.minimize(loss)
+        return loss
+
+    image = fluid.data(name='image', shape=[None, IMAGE_SIZE], dtype='float32')
+    label = fluid.data(name='label', shape=[None, 1], dtype='int64')
+
+    loss = simple_net(image, label)
+
+    exe = fluid.Executor(places[0])
+    exe.run(fluid.default_startup_program())
+
+    prog = fluid.CompiledProgram(fluid.default_main_program()).with_data_parallel(loss_name=loss.name)
+
+    dataset = RandomDataset(BATCH_NUM * BATCH_SIZE)
+
+    loader = DataLoader(dataset,
+                        feed_list=[image, label],
+                        places=places,
+                        batch_size=BATCH_SIZE, 
+                        shuffle=True,
+                        drop_last=True,
+                        num_workers=2)
+
+    for e in range(EPOCH_NUM):
+        for i, data in enumerate(loader()):
+            l = exe.run(prog, feed=data, fetch_list=[loss], return_numpy=True)
+            print("Epoch {} batch {}: loss = {}".format(e, i, l[0][0]))
+
+    # -------------------------------------------------------
+        
+    # -------------------- dynamic graph --------------------
+
+    class SimpleNet(fluid.dygraph.Layer):
+        def __init__(self):
+            super(SimpleNet, self).__init__()
+            self.fc = fluid.dygraph.nn.Linear(IMAGE_SIZE, CLASS_NUM, act='softmax')
+
+        def forward(self, image, label=None):
+            return self.fc(image)
+
+    with fluid.dygraph.guard(places[0]):
+        simple_net = SimpleNet()
+        opt = fluid.optimizer.SGD(learning_rate=1e-3,
+                                  parameter_list=simple_net.parameters())
+
+        loader = DataLoader(dataset,
+                            places=places[0],
+                            batch_size=BATCH_SIZE,
+                            shuffle=True,
+                            drop_last=True,
+                            num_workers=2)
+
+        for e in range(EPOCH_NUM):
+            for i, (image, label) in enumerate(loader()):
+                out = simple_net(image)
+                loss = fluid.layers.cross_entropy(out, label)
+                avg_loss = fluid.layers.reduce_mean(loss)
+                avg_loss.backward()
+                opt.minimize(avg_loss)
+                simple_net.clear_gradients()
+                print("Epoch {} batch {}: loss = {}".format(e, i, np.mean(loss.numpy())))
+
+    # -------------------------------------------------------
 
 
 .. py:method:: from_generator(feed_list=None, capacity=None, use_double_buffer=True, iterable=True, return_list=False, use_multiprocess=False)

doc/fluid/api_cn/io_cn/Dataset_cn.rst

+.. _cn_api_fluid_io_Dataset:
+
+Dataset
+-------------------------------
+
+.. py:class:: paddle.fluid.io.Dataset()
+
+概述Dataset的方法和行为的抽象类。
+
+映射式(map-style)数据集需要继承这个基类，映射式数据集为可以通过一个键值索引并获取指定样本的数据集，所有映射式数据集须实现以下方法：
+
+``__getitem__`` : 根据给定索引获取数据集中指定样本，在 ``fluid.io.DataLoader`` 中需要使用此函数通过下标获取样本。
+
+``__len__`` : 返回数据集样本个数， ``fluid.io.BatchSampler`` 中需求样本个数来生成下标序列。

doc/fluid/api_cn/io_cn/Flowers_cn.rst

+.. _cn_api_fluid_io_Flowers:
+
+Flowers
+-------------------------------
+
+.. py:class:: paddle.fluid.io.Flowers(data_file=None, label_file=None, setid_file=None, mode='train', download=True)
+
+Flowers数据集
+
+参数:
+    - **data_file** (str) - 数据集数据文件路径，若 ``download`` 为True， ``data_file`` 可设置为None。默认值为None。
+    - **label_file** (str) - 数据集数据文件路径，若 ``download`` 为True， ``label_file`` 可设置为None。默认值为None。
+    - **setid_file** (str) - 数据集数据文件路径，若 ``download`` 为True， ``setid_file`` 可设置为None。默认值为None。
+    - **mode** (str) - 数据集模式，即读取 ``'train'`` ``valid`` 或者 ``'test'`` 数据。默认值为 ``'train'`` 。
+    - **download** (bool) - 当 ``data_file`` ``label_file`` 或 ``setid_file`` 为None时，是否自动下载数据集。默认值为True。
+
+返回：Flowers数据集
+
+返回类型: Dataset
+
+**代码示例**
+
+.. code-block:: python
+
+    from paddle.fluid.io import Flowers
+
+    flowers = Flowers(mode='test')
+
+    for i in range(len(flowers)):
+        sample = flowers[i]
+        print(sample[0].shape, sample[1])

doc/fluid/api_cn/io_cn/MNIST_cn.rst

+.. _cn_api_fluid_io_MNIST:
+
+MNIST
+-------------------------------
+
+.. py:class:: paddle.fluid.io.MNIST(image_path=None, label_path=None, mode='train', download=True)
+
+MNIST数据集
+
+参数:
+    - **image_path** (str) - 数据集图像文件路径，若 ``download`` 为True， ``image_path`` 可设置为None。默认值为None。
+    - **label_path** (str) - 数据集标注文件路径，若 ``download`` 为True， ``label_path`` 可设置为None。默认值为None。
+    - **mode** (str) - 数据集模式，即读取 ``'train'`` 或者 ``'test'`` 数据。默认值为 ``'train'`` 。
+    - **download** (bool) - 当 ``image_path`` 或 ``label_path`` 为None时，是否自动下载数据集。默认值为True。
+
+返回：MNIST数据集
+
+返回类型: Dataset
+
+**代码示例**
+
+.. code-block:: python
+
+    from paddle.fluid.io import MNIST
+
+    mnist = MNIST(mode='test')
+
+    for i in range(len(mnist)):
+        sample = mnist[i]
+        print(sample[0].shape, sample[1])
+