Update doc of API：slice, reshape, expand, pow (#1165)

* update slice_cn.rst test=document_preview

*  update reshape_cn.rst test=document_preview

*  update pow_cn.rst test=document_preview

* update expand_cn.rst test=document_preview

* add result of output. test=document_preview

doc/fluid/api_cn/layers_cn/expand_cn.rst

@@ -27,7 +27,7 @@ expand运算会按给定的次数对输入各维度进行复制（tile）运算
 
 参数:
         - **x** (Variable)- 一个秩在[1, 6]范围中的张量（Tensor）.
-        - **expand_times** (list|tuple) - 每一个维度要扩展的次数.
+        - **expand_times** (list|tuple|Variable) - 每一个维度要扩展的次数。
 
 返回：     expand变量是LoDTensor。expand运算后，输出（Out）的每个维度的大小等于输入（X）的相应维度的大小乘以 ``expand_times`` 给出的相应值。
 
@@ -38,10 +38,17 @@ expand运算会按给定的次数对输入各维度进行复制（tile）运算
 ..  code-block:: python
 
         import paddle.fluid as fluid
-        x = fluid.layers.fill_constant(shape=[2, 3, 1], dtype='int32', value=0)
-        out = fluid.layers.expand(x=x, expand_times=[1, 2, 2])
 
+        # example 1:
+        data_1 = fluid.layers.fill_constant(shape=[2, 3, 1], dtype='int32', value=0)
+        expanded_1 = fluid.layers.expand(data_1, expand_times=[1, 2, 2])
+        # the shape of expanded_1 is [2, 6, 2].
 
+        # example 2:
+        data_2 = fluid.layers.fill_constant(shape=[12, 14], dtype="int32", value=3)
+        expand_times = fluid.layers.fill_constant(shape=[2], dtype="int32", value=4)
+        expanded_2 = fluid.layers.expand(data_2, expand_times=expand_times)
+        # the shape of expanded_2 is [48, 56].
 
 
 

doc/fluid/api_cn/layers_cn/pow_cn.rst

@@ -12,8 +12,8 @@ pow
     out = x^{factor}
 
 参数
-    - **x** (Variable) - Pow operator的输入
-    - **factor** (FLOAT|1.0) - Pow的指数因子
+    - **x** (Variable) - Pow operator的输入。
+    - **factor** (FLOAT|Variable|1.0) - Pow的指数因子。
     - **name** (str|None) -这个层的名称(可选)。如果设置为None，该层将被自动命名。
 
 返回: 输出Pow操作符
@@ -26,8 +26,17 @@ pow
 .. code-block:: python
 
     import paddle.fluid as fluid
+
     x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32")
-    y = fluid.layers.pow(x, factor=2.0)
+
+    # example 1: argument factor is float
+    y_1 = fluid.layers.pow(x, factor=2.0)
+    # y_1 is x^{2.0}
+
+    # example 2: argument factor is Variable
+    factor_tensor = fluid.layers.fill_constant([1], "float32", 3.0)
+    y_2 = fluid.layers.pow(x, factor=factor_tensor)
+    # y_2 is x^{2.0}
 
 
 

doc/fluid/api_cn/layers_cn/reshape_cn.rst

@@ -7,8 +7,8 @@ reshape
 
 保持输入张量数据不变的情况下，改变张量的形状。
 
-目标形状可由 ``shape`` 或 ``actual_shape`` 给出。``shape`` 是一个整数列表，而 ``actual_shape`` 是一个张量变量。
-当两个属性同时被指定时，``actual_shape`` 的优先级高于 ``shape`` ，但在编译时仍然应该正确地设置 ``shape`` 以保证形状推断。
+目标形状可由 ``shape`` 或 ``actual_shape`` 给出。``shape`` 可以是一个包含整数或张量的列表，或者是一个张量变量，而 ``actual_shape`` 是一个张量变量。
+当两个属性同时被指定时，``actual_shape`` 的优先级高于 ``shape`` ，但此时 ``shape`` 只能是整数列表，且在编译时仍然应该正确地设置 ``shape`` 以保证形状推断。
 
 在指定目标shape时存在一些技巧：
 
@@ -26,27 +26,40 @@ reshape
   2. 给定一个形状为[2,4,6]的三维张量x，指定的目标形状为[2,3,-1,2]， ``reshape``将x变换为形状为[2,3,4,2]的4- d张量，不改变x的数据。在这种情况下，目标形状的一个维度被设置为-1，这个维度的值是从x的元素总数和剩余维度推断出来的。
   3. 给定一个形状为[2,4,6]的三维张量x，目标形状为[- 1,0,3,2]，整形算子将x变换为形状为[2,4,3,2]的四维张量，使x的数据保持不变。在这种情况下，0意味着实际的维值将从x的对应维数中复制,-1位置的维度由x的元素总数和剩余维度计算得来。
 
+**注意:** 参数``actual_shape`` 之后将被舍弃，只用参数 ``shape`` 来表示目标形状。
+
 参数：
-  - **x** (variable) - 输入张量
-  - **shape** (list) - 新的形状。新形状最多只能有一个维度为-1。
-  - **actual_shape** (variable) - 一个可选的输入。如果提供，则根据 ``actual_shape`` 进行 reshape，而不是指定 ``shape`` 。也就是说，actual_shape具有比shape更高的优先级。
-  - **act** (str) - 对reshpe后的tensor变量执行非线性激活
+  - **x** (Variable) - 输入张量。
+  - **shape** (list|tuple|Variable) - 新的形状。新形状最多只能有一个维度为-1。如果 ``shape``是一个 list 或 tuple, 它可以包含整数或者 Variable 类型的元素，但是 Variable 类型元素的形状只能是[1]。
+  - **actual_shape** (Variable) - 一个可选的输入。如果提供，则根据 ``actual_shape`` 进行 reshape，而不是指定 ``shape`` 。也就是说，``actual_shape`` 具有比 ``shape`` 更高的优先级，此时 ``shape`` 只能是整数列表。 ``actual_shape`` 将在未来的版本中舍弃。更新提示：``actual_shape`` 将被舍弃并用 ``shape`` 代替。
+  - **act** (str) - 对reshpe后的tensor变量执行非线性激活。
   - **inplace** (bool) - 如果 ``inplace`` 为True，则 ``layers.reshape`` 的输入和输出是同一个变量，否则， ``layers.reshape`` 的输入和输出是不同的变量。请注意，如果x作为多个层的输入，则 ``inplace`` 必须为False。
-  - **name** (str) -  可选变量，此层的名称
+  - **name** (str) -  可选变量，此层的名称。
 
 返回：如果 ``act`` 为 ``None``,返回reshape后的tensor变量。如果 ``inplace`` 为 ``False`` ,将返回一个新的Tensor变量，否则，将改变x自身。如果 ``act`` 不是 ``None`` ，则返回激活的张量变量。
 
-抛出异常：``TypeError`` - 如果 actual_shape 既不是变量也不是None
+抛出异常：``TypeError`` - 如果 actual_shape 既不是变量也不是None.
 
 **代码示例**
 
 .. code-block:: python
 
   import paddle.fluid as fluid
-  data = fluid.layers.data(
-      name='data', shape=[2, 4, 6], dtype='float32')
-  reshaped = fluid.layers.reshape(
-      x=data, shape=[-1, 0, 3, 2], inplace=True)
+
+  # example 1:
+  # attr shape is a list which doesn't contain tensor Variable.
+  data_1 = fluid.layers.data(
+      name='data_1', shape=[2, 4, 6], dtype='float32')
+  reshaped_1 = fluid.layers.reshape(
+      x=data_1, shape=[-1, 0, 3, 2], inplace=True)
+  # the shape of reshaped_1 is [2,4,3,2].
+
+  # example 2:
+  # attr shape is a list which contains tensor Variable.
+  data_2 = fluid.layers.fill_constant([2,25], "int32", 3)
+  dim = fluid.layers.fill_constant([1], "int32", 5)
+  reshaped_2 = fluid.layers.reshape(data_2, shape=[dim, 10])
+  # the shape of reshaped_2 is [5,10].
 
 
 

doc/fluid/api_cn/layers_cn/slice_cn.rst

@@ -31,8 +31,8 @@ slice算子。
 参数：
         - **input** （Variable）- 提取切片的数据张量（Tensor）。
         - **axes** （List）- （list <int>）开始和结束的轴适用于。它是可选的。如果不存在，将被视为[0,1，...，len（starts）- 1]。
-        - **starts** （List）- （list <int>）在轴上开始相应轴的索引。
-        - **ends** （List）- （list <int>）在轴上结束相应轴的索引。
+        - **starts** （List|Variable）- （list <int>）在轴上开始相应轴的索引。
+        - **ends** （List|Variable）- （list <int>）在轴上结束相应轴的索引。
 
 返回：        切片数据张量（Tensor）.
 
@@ -45,15 +45,23 @@ slice算子。
 
     import paddle.fluid as fluid
 
-    starts = [1, 0, 2]
-    ends = [3, 3, 4]
-    axes = [0, 1, 2]
-
     input = fluid.layers.data(
         name="input", shape=[3, 4, 5, 6], dtype='float32')
 
-    out = fluid.layers.slice(input, axes=axes, starts=starts, ends=ends)
+    # example 1:
+    # attr starts is a list which doesn't contain tensor Variable.
+    axes = [0, 1, 2]
+    starts = [-3, 0, 2]
+    ends = [3, 2, 4]
+    sliced_1 = fluid.layers.slice(input, axes=axes, starts=starts, ends=ends)
+    # sliced_1 is input[:, 0:3, 0:2, 2:4].
+
 
+    # example 2:
+    # attr starts is a list which contain tensor Variable.
+    minus_3 = fluid.layers.fill_constant([1], "int32", -3)
+    sliced_2 = fluid.layers.slice(input, axes=axes, starts=[minus_3, 0, 2], ends=ends)
+    # sliced_2 is input[:, 0:3, 0:2, 2:4].