Merge branch 'update_api_style' of https://github.com/TCChenlong/docs into update_api_style

Author: TCChenlong

docs/api/paddle/static/BuildStrategy_cn.rst

@@ -9,7 +9,7 @@ BuildStrategy
 
 返回
 :::::::::
-BuildStrategy，一个BuildStrategy的实例
+BuildStrategy，一个BuildStrategy的实例。
 
 代码示例
 :::::::::

docs/api/paddle/static/CompiledProgram_cn.rst

@@ -11,12 +11,12 @@ CompiledProgram根据 `build_strategy` 的配置将输入的Program或Graph进
 
 参数
 :::::::::
-    - **program_or_graph** (Graph|Program): 该参数为被执行的Program或Graph。
-    - **build_strategy** (BuildStrategy): 通过配置build_strategy，对计算图进行转换和优化，例如：计算图中算子融合、计算图执行过程中开启内存/显存优化等。关于build_strategy更多信息，请参阅  ``fluid.BuildStrategy`` 。 默认为None。
+    - **program_or_graph** (Graph|Program)：该参数为被执行的Program或Graph。
+    - **build_strategy** (BuildStrategy)：通过配置build_strategy，对计算图进行转换和优化，例如：计算图中算子融合、计算图执行过程中开启内存/显存优化等。关于build_strategy更多信息，请参阅  ``fluid.BuildStrategy`` 。 默认为None。
 
 返回
 :::::::::
-CompiledProgram，初始化后的 ``CompiledProgram`` 对象
+CompiledProgram，初始化后的 ``CompiledProgram`` 对象。
 
 代码示例
 ::::::::::
@@ -34,14 +34,16 @@ with_data_parallel(loss_name=None, build_strategy=None, exec_strategy=None, shar
     如果在构建CompiledProgram和调用with_data_parallel时都指定了build_strategy，在CompiledProgram中的build_strategy会被复写，因此，如果是数据并行训练，建议在调用with_data_parallel接口时设置build_strategy。
 
 **参数**
+
     - **loss_name** （str） - 该参数为模型最后得到的损失变量的名字，**注意：如果是模型训练，必须设置loss_name，否则计算结果可能会有问题。** 默认为：None。
     - **build_strategy** （BuildStrategy）: 通过配置build_strategy，对计算图进行转换和优化，例如：计算图中算子融合、计算图执行过程中开启内存/显存优化等。关于build_strategy更多的信息，请参阅  ``fluid.BuildStrategy`` 。 默认为：None。
     - **exec_strategy** （ExecutionStrategy） -  通过exec_strategy指定执行计算图过程可以调整的选项，例如线程池大小等。 关于exec_strategy更多信息，请参阅 ``fluid.ExecutionStrategy`` 。 默认为：None。
     - **share_vars_from** （CompiledProgram） - 如果设置了share_vars_from，当前的CompiledProgram将与share_vars_from指定的CompiledProgram共享参数值。需要设置该参数的情况：模型训练过程中需要进行模型测试，并且训练和测试都是采用数据并行模式，那么测试对应的CompiledProgram在调用with_data_parallel时，需要将share_vars_from设置为训练对应的CompiledProgram。由于CompiledProgram只有在第一次执行时才会将变量分发到其他设备上，因此share_vars_from指定的CompiledProgram必须在当前CompiledProgram之前运行。默认为：None。
     - **places** （list(CUDAPlace)|list(CPUPlace)） - 该参数指定模型运行所在的设备。如果希望在GPU0和GPU1上运行，places为[fluid.CUDAPlace(0), fluid.CUDAPlace(1)]；如果希望使用2个CPU运行，places为[fluid.CPUPlace()] * 2。 如果没有设置该参数，即该参数为None，模型执行时，将从环境变量中获取可用的设备：如果使用GPU，模型执行时，从环境变量FLAGS_selected_gpus或CUDA_VISIBLE_DEVICES中获取当前可用的设备ID；如果使用CPU，模型执行时，从环境变量CPU_NUM中获取当前可利用的CPU个数。例如：export CPU_NUM=4，如果没有设置该环境变量，执行器会在环境变量中添加该变量，并将其值设为1。默认为：None。
 
 **返回**
-CompiledProgram，配置之后的 ``CompiledProgram`` 对象
+
+CompiledProgram，配置之后的 ``CompiledProgram`` 对象。
 
 .. note::
      1. 如果只是进行多卡测试，不需要设置loss_name以及share_vars_from。

docs/api/paddle/static/ExecutionStrategy_cn.rst

@@ -10,7 +10,7 @@ ExecutionStrategy
 
 返回
 :::::::::
-ExecutionStrategy，一个ExecutionStrategy的实例
+ExecutionStrategy，一个ExecutionStrategy的实例。
 
 代码示例
 :::::::::

docs/api/paddle/static/Executor_cn.rst

@@ -15,11 +15,15 @@ Executor支持单GPU、多GPU以及CPU运行。
 参数
 ::::::::::::
 
-    - **place** (paddle.CPUPlace()|paddle.CUDAPlace(N)|None) – 该参数表示Executor执行所在的设备，这里的N为GPU对应的ID。当该参数为 `None` 时，PaddlePaddle会根据其安装版本设置默认的运行设备。当安装的Paddle为CPU版时，默认运行设置会设置成 `CPUPlace()` ，而当Paddle为GPU版时，默认运行设备会设置成 `CUDAPlace(0)` 。默认值为None。注意：多卡训练初始化Executor时也只用传入一个Place或None，其他API会处理使用的多卡，见 `多卡使用方式 <https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/01_paddle2.0_introduction/update_cn.html#danjiduokaqidong>`_ 
+    - **place** (paddle.CPUPlace()|paddle.CUDAPlace(N)|None) – 该参数表示Executor执行所在的设备，这里的N为GPU对应的ID。当该参数为 `None` 时，PaddlePaddle会根据其安装版本设置默认的运行设备。当安装的Paddle为CPU版时，默认运行设置会设置成 `CPUPlace()` ，而当Paddle为GPU版时，默认运行设备会设置成 `CUDAPlace(0)` 。默认值为None。
+    
+
+.. note::
+多卡训练初始化Executor时也只用传入一个Place或None，其他API会处理使用的多卡，见 `多卡使用方式 <https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/01_paddle2.0_introduction/update_cn.html#danjiduokaqidong>`_ 
 
 返回
 ::::::::::::
-初始化后的 ``Executor`` 对象
+初始化后的 ``Executor`` 对象。
 
 代码示例
 ::::::::::::
@@ -85,7 +89,8 @@ close()
 关闭执行器。该接口主要用于对于分布式训练，调用该接口后不可以再使用该执行器。该接口会释放在PServers上和目前Trainer有关联的资源。
 
 **返回**
-无
+
+无。
 
 **代码示例**
 
@@ -118,7 +123,8 @@ run(program=None, feed=None, fetch_list=None, feed_var_name='feed', fetch_var_na
   - **use_prune** (bool) - 该参数表示输入Program是否会被裁剪。如果该参数为True，会根据feed和fetch_list裁剪Program，这意味着对生成fetch_list没有必要的算子和变量会被裁剪掉。默认为False，即算子和变量在运行过程不会被裁剪。注意如果Optimizer.minimize()返回的tuple被作为fetch_list参数，那么use_prune会被重载为True并且Program会被裁剪。
 
 **返回**
-返回fetch_list中指定的变量值
+
+返回fetch_list中指定的变量值。
 
 .. note::
      1. 如果是多卡训练，并且feed参数为dict类型，输入数据将被均匀分配到不同的卡上，例如：使用2块GPU训练，输入样本数为3，即[0, 1, 2]，经过拆分之后，GPU0上的样本数为1，即[0]，GPU1上的样本数为2，即[1, 2]。如果样本数少于设备数，程序会报错，因此运行模型时，应额外注意数据集的最后一个batch的样本数是否少于当前可用的CPU核数或GPU卡数，如果是少于，建议丢弃该batch。
@@ -229,17 +235,18 @@ infer_from_dataset的文档与train_from_dataset几乎完全相同，只是在
 
 **参数**
 
-  - **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)
-  - **dataset** (paddle.fluid.Dataset) – 在此函数外创建的数据集，用户应当在调用函数前提供完整定义的数据集。必要时请检查Dataset文件。默认为None
-  - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。默认为全局域
-  - **thread** (int) – 用户想要在这个函数中运行的线程数量。线程的实际数量为min(Dataset.thread_num, thread)，如果thread > 0，默认为0
-  - **debug** (bool) – 是否开启debug模式，默认为False
-  - **fetch_list** (Tensor List) – 返回变量列表，每个变量都会在预测过程中被打印出来，默认为None
-  - **fetch_info** (String List) – 每个变量的打印信息，默认为None
-  - **print_period** (int) – 每两次打印之间间隔的mini-batches的数量，默认为100
+  - **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)。
+  - **dataset** (paddle.fluid.Dataset) – 在此函数外创建的数据集，用户应当在调用函数前提供完整定义的数据集。必要时请检查Dataset文件。默认为None。
+  - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。默认为全局域。
+  - **thread** (int) – 用户想要在这个函数中运行的线程数量。线程的实际数量为min(Dataset.thread_num, thread)，如果thread > 0，默认为0。
+  - **debug** (bool) – 是否开启debug模式，默认为False。
+  - **fetch_list** (Tensor List) – 返回变量列表，每个变量都会在预测过程中被打印出来，默认为None。
+  - **fetch_info** (String List) – 每个变量的打印信息，默认为None。
+  - **print_period** (int) – 每两次打印之间间隔的mini-batches的数量，默认为100。
 
 **返回**
-None
+
+无。
 
 **代码示例**
 
@@ -268,21 +275,23 @@ train_from_dataset(program=None, dataset=None, scope=None, thread=0, debug=False
 
 从预定义的数据集中训练。 数据集在paddle.fluid.dataset中定义。 给定程序（或编译程序），train_from_dataset将使用数据集中的所有数据样本。 输入范围可由用户给出。 默认情况下，范围是global_scope()。训练中的线程总数是thread。 训练中使用的线程数将是数据集中threadnum的最小值，同时也是此接口中线程的值。 可以设置debug，以便执行器显示所有算子的运行时间和当前训练任务的吞吐量。
 
-注意：train_from_dataset将销毁每次运行在executor中创建的所有资源。
+.. note::
+train_from_dataset将销毁每次运行在executor中创建的所有资源。
 
 **参数**
 
-  - **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)
-  - **dataset** (paddle.fluid.Dataset) – 在此函数外创建的数据集，用户应当在调用函数前提供完整定义的数据集。必要时请检查Dataset文件。默认为None
-  - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。默认为全局域
-  - **thread** (int) – 用户想要在这个函数中运行的线程数量。线程的实际数量为min(Dataset.thread_num, thread)，如果thread > 0，默认为0
-  - **debug** (bool) – 是否开启debug模式，默认为False
-  - **fetch_list** (Tensor List) – 返回变量列表，每个变量都会在训练过程中被打印出来，默认为None
-  - **fetch_info** (String List) – 每个变量的打印信息，默认为None
-  - **print_period** (int) – 每两次打印之间间隔的mini-batches的数量，默认为100
+  - **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)。
+  - **dataset** (paddle.fluid.Dataset) – 在此函数外创建的数据集，用户应当在调用函数前提供完整定义的数据集。必要时请检查Dataset文件。默认为None。
+  - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。默认为全局域。
+  - **thread** (int) – 用户想要在这个函数中运行的线程数量。线程的实际数量为min(Dataset.thread_num, thread)，如果thread > 0，默认为0。
+  - **debug** (bool) – 是否开启debug模式，默认为False。
+  - **fetch_list** (Tensor List) – 返回变量列表，每个变量都会在训练过程中被打印出来，默认为None。
+  - **fetch_info** (String List) – 每个变量的打印信息，默认为None。
+  - **print_period** (int) – 每两次打印之间间隔的mini-batches的数量，默认为100。
 
 **返回**
-None
+
+无。
 
 **代码示例**
 

docs/api/paddle/static/ExponentialMovingAverage_cn.rst

@@ -12,12 +12,16 @@ ExponentialMovingAverage
 
 用 ``update()`` 方法计算出的平均结果将保存在由实例化对象创建和维护的临时变量中，并且可以通过调用 ``apply()`` 方法把结果应用于当前模型的参数。同时，可用 ``restore()`` 方法恢复原始参数。
 
-**偏置校正**  所有的滑动平均均初始化为 :math:`0` ，因此它们相对于零是有偏的，可以通过除以因子 :math:`(1 - \text{decay}^t)` 来校正，因此在调用 ``apply()`` 方法时，作用于参数的真实滑动平均值将为：
+**偏置校正**  
+
+所有的滑动平均均初始化为 :math:`0` ，因此它们相对于零是有偏的，可以通过除以因子 :math:`(1 - \text{decay}^t)` 来校正，因此在调用 ``apply()`` 方法时，作用于参数的真实滑动平均值将为：
 
 .. math::
     \widehat{\text{EMA}}_t = \frac{\text{EMA}_t}{1 - \text{decay}^t}
 
-**衰减率调节**  一个非常接近于1的很大的衰减率将会导致平均值滑动得很慢。更优的策略是，开始时设置一个相对较小的衰减率。参数 ``thres_steps`` 允许用户传递一个变量以设置衰减率，在这种情况下，
+**衰减率调节**  
+
+一个非常接近于1的很大的衰减率将会导致平均值滑动得很慢。更优的策略是，开始时设置一个相对较小的衰减率。参数 ``thres_steps`` 允许用户传递一个变量以设置衰减率，在这种情况下，
 真实的衰减率变为：
 
 .. math:: 
@@ -39,27 +43,26 @@ COPY-FROM: paddle.static.ExponentialMovingAverage
 ::::::::::::
 update()
 '''''''''
-'''''''''
 
 更新指数滑动平均，在训练过程中需调用此方法。
 
 
 apply(executor, need_restore=True)
 '''''''''
-'''''''''
 
 模型评测时，将滑动平均的结果作用在参数上。
 
 **参数**
+
     - **executor** (Executor) – 将滑动平均值作用在参数上的执行器。
     - **need_restore** (bool，可选) – 是否在结束后恢复原始参数，默认值为 ``True`` 。
 
 
 restore(executor)
 '''''''''
-''''''''''
 
 恢复参数。
 
 **参数**
+
     - **executor** (Executor) – 执行恢复动作的执行器。

docs/api/paddle/static/InputSpec_cn.rst

@@ -18,11 +18,8 @@ InputSpec
 
 返回
 ::::::::::::
-初始化后的 ``InputSpec`` 对象
+初始化后的 ``InputSpec`` 对象。
 
-返回类型
-::::::::::::
-InputSpec
 
 代码示例
 ::::::::::::
@@ -50,10 +47,8 @@ from_tensor(tensor, name=None)
 
 
 **返回**
-根据Tensor信息构造的 ``InputSpec`` 对象
 
-**返回类型**
-InputSpec
+根据Tensor信息构造的 ``InputSpec`` 对象。
 
 
 **代码示例**
@@ -80,10 +75,8 @@ from_numpy(ndarray, name=None)
 
 
 **返回**
-根据ndarray信息构造的 ``InputSpec`` 对象
 
-**返回类型**
-InputSpec
+根据ndarray信息构造的 ``InputSpec`` 对象。
 
 
 **代码示例**
@@ -107,10 +100,8 @@ batch(batch_size)
   - **batch_size** (int) - 被插入的batch size整型数值
 
 **返回**
- 更新shape信息后的 ``InputSpec`` 对象
 
-**返回类型**
-InputSpec
+ 更新shape信息后的 ``InputSpec`` 对象。
 
 
 **代码示例**
@@ -130,10 +121,8 @@ unbatch()
 
 
 **返回**
- 更新shape信息后的 ``InputSpec`` 对象
 
-**返回类型**
-InputSpec
+ 更新shape信息后的 ``InputSpec`` 对象。
 
 
 **代码示例**

docs/api/paddle/static/IpuCompiledProgram_cn.rst

@@ -17,7 +17,7 @@ IpuCompiledProgram将输入的Program转换和优化成IPU所需要的形式，
 
 返回
 :::::::::
-IpuCompiledProgram，初始化后的 ``IpuCompiledProgram`` 对象
+IpuCompiledProgram，初始化后的 ``IpuCompiledProgram`` 对象。
 
 代码示例
 ::::::::::
@@ -32,11 +32,13 @@ compile(self, feed_list, fetch_list)
 该接口用于将Program进行编译，以便在ipu上运行。用户可以通过 `feed_list` 、`fetch_list` 传入计算图输入和输出的名字。
 
 **参数**
-    - **feed_list** （list）: 该参数为模型的输入变量的名字。
-    - **fetch_list** （list）:  模型运行之后需要返回的变量的名字。
+
+    - **feed_list** (list)：该参数为模型的输入变量的名字。
+    - **fetch_list** (list)：模型运行之后需要返回的变量的名字。
 
 **返回**
-Program，编译之后的 ``Program`` 对象
+
+Program，编译之后的 ``Program`` 对象。
 
 
 **代码示例**

docs/api/paddle/static/IpuStrategy_cn.rst

@@ -12,7 +12,7 @@ IpuStrategy
 
 返回
 :::::::::
-    IpuStrategy实例
+IpuStrategy实例。
 
 代码示例
 ::::::::::
@@ -27,6 +27,7 @@ set_graph_config(self, num_ipus, is_training, micro_batch_size, enable_manual_sh
 该接口用于向IpuStrategy实例传递IPU构图的Graph配置。
 
 **参数**
+
     - **num_ipus** (int，可选)- 指定IPU devices的个数，默认值为1，表示仅用一个IPU。
     - **is_training** (bool，可选)- 声明是训练还是推理，默认值为True，表示使用训练模式。
     - **micro_batch_size** (int，可选)- 当计算图输入的micro_batch_size可变时，指定计算图中输入micro_batch_size，默认值为1，表示如果micro_batch_size可变，将默认置1。
@@ -42,6 +43,7 @@ set_pipelining_config(self, enable_pipelining, batches_per_step, enable_gradient
 该接口用于向IpuStrategy实例传递IPU构图的子图数据流水线配置。
 
 **参数**
+
     - **enable_pipelining** (bool，可选)- 是否使能子图之间的数据流水线。仅支持当enable_manual_shard=True时，enable_pipelining可以置为True。默认值为False，表示不使能该功能。
     - **batches_per_step** (int，可选)- 指定数据流水线每次运算多少个batch的数据。默认值为1，表示不使能数据流水线功能。
     - **enable_gradient_accumulation** (bool，可选)- 是否使能梯度累积，只用于训练模式。默认值为Flase，表示不使能梯度累积功能。
@@ -57,6 +59,7 @@ set_precision_config(self, enable_fp16)
 该接口用于向IpuStrategy实例传递IPU构图的精度配置。
 
 **参数**
+
     - **enable_fp16** (bool)- 是否使能fp16运算模式并将fp32转换为fp16。默认值为False，表示不使能fp16运算模式。
 
 **代码示例**
@@ -69,6 +72,7 @@ add_custom_op(self, paddle_op, popart_op, domain, version)
 该接口用于向IpuStrategy实例传递PopART自定义算子的信息。
 
 **参数**
+
     - **paddle_op** (str)- 待添加的Paddle自定义算子在的名称，根据Paddle自定义算子的定义设置此参数。
     - **popart_op** (str，可选)- 待添加的PopART自定义算子的名称，默认值为None，表示和paddle_op相同，根据PopART自定算子的定义设置此参数。
     - **domain** (str，可选)- 待添加的PopART自定义算子的domain属性，默认值为"custom.ops"，根据PopART自定算子的定义设置此参数。
@@ -84,6 +88,7 @@ set_options(self, options)
 批量向IpuStrategy实例传递参数。
 
 **参数**
+
     - **options** (dict)- 需要传递的参数字典。
 
 **代码示例**
@@ -96,6 +101,7 @@ get_option(self, option)
 获取IpuStrategy实例的某一参数。
 
 **参数**
+
     - **option** (str)- 需要获取参数的名称。
 
 **代码示例**
@@ -108,6 +114,7 @@ enable_pattern(self, pattern)
 启用某一PopART Pattern。
 
 **参数**
+
     - **pattern** (str)- 需要开启的Pattern名称。
 
 **代码示例**
@@ -120,14 +127,13 @@ disable_pattern(self, pattern)
 禁用某一PopART Pattern。
 
 **参数**
+
     - **pattern** (str)- 需要禁用的Pattern名称。
 
 **代码示例**
 
 COPY-FROM: paddle.static.IpuStrategy.disable_pattern
 
-属性
-::::::::::::
 属性
 ::::::::::::
 num_ipus