refine append-backward & in_dygraph_mode cn (#1211)

* refine append-backward cn

* refine in_dygraph_mode, test=develop

* refine default statements, test=develop

* add links, test=develop

* fix links, test=develop

* add blank beside links, test=develop

* refine, test=develop

* refine, test=develop

doc/fluid/api_cn/backward_cn/append_backward_cn.rst

@@ -5,40 +5,43 @@ append_backward
 
 .. py:function:: paddle.fluid.backward.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None)
 
-将向 ``main_program`` 追加 ``backward`` 。
+该接口将向主程序（``main_program``）追加反向部分 。
 
-完整的神经网络训练由前向和反向传播组成。但是当我们配置网络时，我们只需要指定其前向部分。通过该功能，根据前向部分自动生成反向部分。
+完整的神经网络训练由前向和反向传播组成。但是当我们配置网络时，我们只需要指定其前向部分。
+该接口使用链式法则，能够根据前向部分自动生成反向部分。
 
-在大多数情况下，用户无需手动调用此功能。它将由优化程序的最小化函数自动调用。
+在大多数情况下，用户无需手动调用此接口，它将由优化器（``Optimizer``）的 ``minimize`` 函数自动调用。
 
 参数：
-    - **loss** （Variable）- 网络的损失变量。
-    - **parameter_list** （list [string] | None）- 优化器需要更新的参数名称。如果为None，则将更新所有参数。默认值：None。
-    - **no_grad_set** （set | None）- ``block`` 0中变量的梯度应该被忽略。所有 ``block`` 中带有 ``step_gradient = True`` 的所有变量都将自动添加到此集合中。默认值：None。
-    - **callbacks** （list [callable object] | None）- 回调用于在反向传播构建中执行一些自定义作业。每次将新的梯度运算符添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数： ``block`` 和 ``context`` 。 ``block`` 是将被添加到新梯度算子的块。 ``context`` 是一个映射，其键是梯度变量名，值是对应的原始变量。除此之外， ``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__`` ，值是刚刚触发可调用对象的梯度运算符的 ``op_desc`` 。
+    - **loss** ( :ref:`api_guide_Variable` ) - 网络的损失变量。
+    - **parameter_list** （list [str]，可选）- 指定优化器需要更新的参数名称列表。如果为 ``None`` ，则将更新所有参数。默认值为 ``None``。
+    - **no_grad_set** （set [str]，可选）-  在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 :ref:`api_guide_Variable` 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 :ref:`api_guide_Variable` 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。
+    - **callbacks** （list [callable object]，可选）- 回调函数列表。用于在反向传播构建中执行一些自定义作业。每次将新的梯度OP添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数： :ref:`api_guide_Block` 和 ``context`` 。 :ref:`api_guide_Block` 是将被添加到新梯度算子的块。 ``context`` 是一个映射，其键是梯度 :ref:`api_guide_Variable` 名，值是对应的原始 :ref:`api_guide_Variable` 。除此之外， ``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__`` ，值是刚刚触发可调用对象的梯度OP的 ``op_desc`` 。默认值为 ``None``。
 
-返回：   成对参数及其相应的梯度。键是参数，值是梯度变量。
+返回：   参数及其梯度 :ref:`api_guide_Variable` 的元组的列表。元组的第一个值为参数，第二个值为该参数的梯度 :ref:`api_guide_Variable` 。
 
-返回类型：       list[(Variable,Variable)]
+返回类型：       list[( :ref:`api_guide_Variable` , :ref:`api_guide_Variable` )]
 
 抛出：     
-    - ``AssertionError`` - 如果loss不是Variable的实例。
+    - ``AssertionError`` - 如果 loss 不是 :ref:`api_guide_Variable` 的实例。
 
 **示例代码**
 
 .. code-block:: python
 
-        # 网络配置
-        # 损失计算
         import paddle.fluid as fluid
+
         x = fluid.layers.data(name='x', shape=[13], dtype='float32')
-        y = fluid.layers.data(name='y', shape=[1], dtype='float32') 
-              
+        y = fluid.layers.data(name='y', shape=[1], dtype='float32')
         y_predict = fluid.layers.fc(input=x, size=1, act=None)
         loss = fluid.layers.square_error_cost(input=y_predict, label=y)
-        
         avg_loss = fluid.layers.mean(loss)
-        param_grad_list = fluid.backward.append_backward(loss=avg_loss)
+
+        p_g_list1 = fluid.backward.append_backward(loss=avg_loss)  # len(p_g_list1) == 2
+        p_g_list2 = fluid.backward.append_backward(loss=avg_loss, parameter_list=[p_g_list1[0][0].name])  # len(p_g_list1) == 1
+        p_g_list3 = fluid.backward.append_backward(loss=avg_loss, no_grad_set=set([p_g_list1[0][0].name]))  # len(p_g_list1) == 1
+        p_g_list4 = fluid.backward.append_backward(loss=avg_loss, parameter_list=[p_g_list1[0][0].name], no_grad_set=set([p_g_list1[0][0].name]))  # len(p_g_list1) == 0
+
 
 
 

doc/fluid/api_cn/fluid_cn/in_dygraph_mode_cn.rst

@@ -5,18 +5,22 @@ in_dygraph_mode
 
 .. py:function:: paddle.fluid.in_dygraph_mode()
 
-检查程序状态(tracer) - 是否在dygraph模式中运行
+该接口检查程序是否在动态图模式中运行。
+可以通过 ``fluid.dygraph.guard`` 接口开启动态图模式。
 
-返回：如果Program是在动态图模式下运行的则为True。
+返回：如果程序是在动态图模式下运行的，则返回 ``True``。
 
-返回类型：out(boolean)
+返回类型：bool
 
 **示例代码**
 
 .. code-block:: python
 
+    from __future__ import print_function
     import paddle.fluid as fluid
     if fluid.in_dygraph_mode():
-        pass
+        print('running in dygraph mode')
+    else:
+        print('not running in dygraph mode')