Refine API docs of scale, selu, shape, split, soft_relu (#1215)

* refine api docs of scale, selu, shape, split, soft_relu. test=develop, test=document_preview

* refine sample codes for api docs, test=develop

* add result comments for sample codes, test=develop

doc/fluid/api_cn/layers_cn/scale_cn.rst

@@ -5,40 +5,49 @@ scale
 
 .. py:function:: paddle.fluid.layers.scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None)
 
-缩放算子
+缩放算子。
 
-对输入张量应用缩放和偏移加法。
+对输入Tensor进行缩放和偏置，其公式如下：
 
-if ``bias_after_scale`` = True:
+``bias_after_scale`` 为True:
 
 .. math::
-                                Out=scale*X+bias
+                        Out=scale*X+bias
 
-else:
+``bias_after_scale`` 为False:
 
 .. math::
-                                Out=scale*(X+bias)
+                        Out=scale*(X+bias)
 
 参数:
-        - **x** (Variable) - (Tensor) 要比例运算的输入张量（Tensor）。
-        - **scale** (FLOAT) - 比例运算的比例因子。
-        - **bias** (FLOAT) - 比例算子的偏差。
-        - **bias_after_scale** (BOOLEAN) - 在缩放之后或之前添加bias。在某些情况下，对数值稳定性很有用。
-        - **act** (basestring|None) - 应用于输出的激活函数。
-        - **name** (basestring|None)- 输出的名称。
+        - **x** (Variable) - 要进行缩放的多维Tensor，数据类型可以为int8，uint8，int16，int32，int64，float32，float64。
+        - **scale** (float) - 缩放的比例。
+        - **bias** (float) - 缩放的的偏置。 
+        - **bias_after_scale** (bool) - 判断在缩放之前或之后添加偏置。为True时，先缩放再偏置；为False时，先偏置再缩放。该参数在某些情况下，对数值稳定性很有用。
+        - **act** (str，可选) - 应用于输出的激活函数，如tanh、softmax、sigmoid、relu等。
+        - **name** (str，可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回:        比例算子的输出张量(Tensor)
+返回: 缩放后的输出Tensor。
 
-返回类型:        变量(Variable)
+返回类型:  Variable(Tensor|LoDTensor)。
 
 **代码示例：**
 
 .. code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
      
-    x = fluid.layers.data(name="X", shape=[1, 2, 5, 5], dtype='float32')
-    y = fluid.layers.scale(x, scale = 2.0, bias = 1.0)
+    inputs = fluid.layers.data(name="x", shape=[2, 3], dtype='float32')
+    output = fluid.layers.scale(inputs, scale = 2.0, bias = 1.0)
+
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
+
+    img = np.array([[1, 2, 3], [4, 5, 6]]).astype(np.float32)
+
+    res = exe.run(fluid.default_main_program(), feed={'x':img}, fetch_list=[output])
+    print(res) # [array([[ 3.,  5.,  7.], [ 9., 11., 13.]], dtype=float32)]
 
 
 

doc/fluid/api_cn/layers_cn/selu_cn.rst

@@ -5,9 +5,7 @@ selu
 
 .. py:function:: paddle.fluid.layers.selu(x, scale=None, alpha=None, name=None)
 
-**实现Selu运算**
-
-有如下等式：
+SeLU激活函数，其公式如下：
 
 .. math::
     selu= \lambda*
@@ -19,25 +17,32 @@ selu
 输入 ``x`` 可以选择性携带LoD信息。输出和它共享此LoD信息(如果有)。
 
 参数:
-  - **x** (Variable) – 输入张量
-  - **scale** (float, None) – 如果标度没有设置，其默认值为 1.0507009873554804934193349852946。 详情请见： `Self-Normalizing Neural Networks <https://arxiv.org/abs/1706.02515.pdf>`_
-  - **alpha** (float, None) – 如果没有设置改参数, 其默认值为 1.6732632423543772848170429916717。 详情请见： `Self-Normalizing Neural Networks <https://arxiv.org/abs/1706.02515.pdf>`_
-  - **name** (str|None, default None) – 该层命名，若为None则自动为其命名
+  - **x** (Variable) - 输入变量，为数据类型为float32，float64的多维Tensor或者LoDTensor。
+  - **scale** (float，可选) – 可选，表示SeLU激活函数中的λ的值，其默认值为 1.0507009873554804934193349852946。 详情请见： `Self-Normalizing Neural Networks <https://arxiv.org/abs/1706.02515.pdf>`_。
+  - **alpha** (float，可选) – 可选，表示SeLU激活函数中的α的值，其默认值为 1.6732632423543772848170429916717。 详情请见： `Self-Normalizing Neural Networks <https://arxiv.org/abs/1706.02515.pdf>`_。
+  - **name** (str，可选) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回：一个形和输入张量相同的输出张量
+返回：一个Tensor，shape和输入Tensor相同。
 
-返回类型：Variable
+返回类型：Variable(Tensor|LoDTensor)，LoD信息与输入Tensor一致。
 
 **代码示例**
 
 ..  code-block:: python
 
     import paddle.fluid as fluid
-     
-    input = fluid.layers.data(
-         name="input", shape=[3, 9, 5], dtype="float32")
+    import numpy as np
+
+    inputs = fluid.layers.data(name="x", shape=[2, 2], dtype="float32")
+    output = fluid.layers.selu(inputs)
+
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
+
+    img = np.array([[0, 1],[2, 3]]).astype(np.float32)
 
-    output = fluid.layers.selu(input)
+    res = exe.run(fluid.default_main_program(), feed={'x':img}, fetch_list=[output])
+    print(res) # [array([[0.      , 1.050701],[2.101402, 3.152103]], dtype=float32)]
 
 
 

doc/fluid/api_cn/layers_cn/shape_cn.rst

@@ -7,25 +7,29 @@ shape
 
 shape层。
 
-获得输入变量的形状。
+获得输入Tensor的shape。
 
 参数：
-        - **input** （Variable）-  输入的变量
+        - **input** （Variable）-  输入的多维Tensor，数据类型为int32，int64，float32，float64。
 
-返回： (Tensor），输入变量的形状
+返回： 一个Tensor，表示输入Tensor的shape。
 
-返回类型：    Variable
+返回类型： Variable(Tensor)。
 
 **代码示例：**
 
 .. code-block:: python
 
     import paddle.fluid as fluid
-    input = fluid.layers.data(
-        name="input", shape=[3, 100, 100], dtype="float32")
-    out = fluid.layers.shape(input)
-
-
+    import numpy as np
 
+    inputs = fluid.layers.data(name="x", shape=[3, 100, 100], dtype="float32")
+    output = fluid.layers.shape(inputs)
+    
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
 
+    img = np.ones((3, 100, 100)).astype(np.float32)
 
+    res = exe.run(fluid.default_main_program(), feed={'x':img}, fetch_list=[output])
+    print(res) # [array([  3, 100, 100], dtype=int32)]

doc/fluid/api_cn/layers_cn/soft_relu_cn.rst

@@ -5,23 +5,36 @@ soft_relu
 
 .. py:function:: paddle.fluid.layers.soft_relu(x, threshold=40.0, name=None)
 
-SoftRelu 激活函数
+SoftReLU 激活函数.
 
 .. math::   out=ln(1+exp(max(min(x,threshold),threshold)))
 
 参数:
-    - **x** (variable) - SoftRelu operator的输入
-    - **threshold** (FLOAT|40.0) - SoftRelu的阈值
-    - **name** (str|None) - 该层的名称(可选)。如果设置为None，该层将被自动命名
+    - **x** (Variable) - SoftReLU激活函数的输入，为数据类型为float32，float64的多维Tensor或者LoDTensor。
+    - **threshold** (float) - SoftRelu的阈值，默认为40.0。
+    - **name** (str，可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
+
+返回：一个Tensor，shape和输入Tensor相同。
+
+返回类型：Variable(Tensor|LoDTensor)，LoD信息与输入Tensor一致。
 
 **代码示例：**
 
 .. code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
+
+    inputs = fluid.layers.data(name="x", shape=[2, 2], dtype="float32")
+    output = fluid.layers.soft_relu(inputs, threshold=20.0)
+
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
+
+    img = np.array([[0, 1],[2, 3]]).astype(np.float32)
 
-    x = fluid.layers.data(name="x", shape=[3,16,16], dtype="float32")
-    y = fluid.layers.soft_relu(x, threshold=20.0)
+    res = exe.run(fluid.default_main_program(), feed={'x':img}, fetch_list=[output])
+    print(res) # [array([[0.6931472, 1.3132616], [2.126928 , 3.0485873]], dtype=float32)]
 
 
 

doc/fluid/api_cn/layers_cn/split_cn.rst

@@ -5,17 +5,17 @@ split
 
 .. py:function:: paddle.fluid.layers.split(input,num_or_sections,dim=-1,name=None)
 
-将输入张量分解成多个子张量
+将输入Tensor分割成多个子Tensor。
 
 参数：
-    - **input** (Variable)-输入变量，类型为Tensor或者LoDTensor
-    - **num_or_sections** (int|list)-如果num_or_sections是整数，则表示张量平均划分为的相同大小子张量的数量。如果num_or_sections是一列整数，列表的长度代表子张量的数量，整数依次代表子张量的dim维度的大小
-    - **dim** (int)-将要划分的维。如果dim<0,划分的维为rank(input)+dim
-    - **name** (str|None)-该层名称（可选）。如果设置为空，则自动为该层命名
+    - **input** (Variable) - 输入变量，为数据类型为int32，int64，float32，float64的多维Tensor或者LoDTensor。
+    - **num_or_sections** (int|list) - 整数或元素为整数的列表。如果\ ``num_or_sections``\ 是一个整数，则表示Tensor平均划分为的相同大小子Tensor的数量。如果\ ``num_or_sections``\ 是一个整数列表，则列表的长度代表子Tensor的数量，列表中的整数依次代表子Tensor的需要分割成的维度的大小。列表长度不能超过输入Tensor待分割的维度的大小。
+    - **dim** (int) - 需要分割的维度。如果dim < 0,划分的维度为rank(input) + dim，数据类型为int32，int64。
+    - **name** (str，可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-返回：一列分割张量
+返回：分割后的Tensor列表。
 
-返回类型：列表(Variable)
+返回类型：列表(Variable(Tensor|LoDTensor))，数据类型为int32，int64，float32，float64。
 
 **代码示例**：
 
@@ -23,19 +23,21 @@ split
 
     import paddle.fluid as fluid
 
-    # 输入是维为[-1, 3,9,5]的张量：
+    # 输入是维度为[-1, 3, 9, 5]的Tensor：
     input = fluid.layers.data(
          name="input", shape=[3, 9, 5], dtype="float32")
 
+    # 传入num_or_sections为一个整数
     x0, x1, x2 = fluid.layers.split(input, num_or_sections=3, dim=2)
-    # x0.shape  [-1, 3, 3, 5]
-    # x1.shape  [-1, 3, 3, 5]
-    # x2.shape  [-1, 3, 3, 5]
-    
-    x0, x1, x2 = fluid.layers.split(input, num_or_sections=3, dim=2)
-    # x0.shape  [-1, 3, 2, 5]
-    # x1.shape  [-1, 3, 3, 5]
-    # x2.shape  [-1, 3, 4, 5]
+    x0.shape  # [-1, 3, 3, 5]
+    x1.shape  # [-1, 3, 3, 5]
+    x2.shape  # [-1, 3, 3, 5]
+
+    # 传入num_or_sections为一个整数列表
+    x0, x1, x2 = fluid.layers.split(input, num_or_sections=[2, 3, 4], dim=2)
+    x0.shape  # [-1, 3, 2, 5]
+    x1.shape  # [-1, 3, 3, 5]
+    x2.shape  # [-1, 3, 4, 5]