refine the doc for split Op test=develop (#2300)

doc/fluid/api_cn/layers_cn/split_cn.rst

@@ -3,7 +3,7 @@
 split
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.split(input,num_or_sections,dim=-1,name=None)
+.. py:function:: paddle.fluid.layers.split(input, num_or_sections, dim=-1, name=None)
 
 
 
@@ -11,18 +11,18 @@ split
 该OP将输入Tensor分割成多个子Tensor。
 
 参数：
-    - **input** (Variable) - 输入变量，数据类型为float32，float64，int32，int64的多维Tensor或者LoDTensor。
+    - **input** (Tensor) - 输入变量，数据类型为bool， float16，float32，float64，int32，int64的多维Tensor。
     - **num_or_sections** (int|list|tuple) - 如果 ``num_or_sections`` 是一个整数，则表示Tensor平均划分为相同大小子Tensor的数量。如果 ``num_or_sections`` 是一个list或tuple，那么它的长度代表子Tensor的数量，它的元素可以是整数或者形状为[1]的Tensor，依次代表子Tensor需要分割成的维度的大小。list或tuple的长度不能超过输入Tensor待分割的维度的大小。至多有一个元素值为-1，-1表示该值是由 ``input`` 待分割的维度值和 ``num_or_sections`` 的剩余元素推断出来的。
-    - **dim** (int|Variable，可选) - 整数或者形状为[1]的Tensor，数据类型为int32或int64。表示需要分割的维度。如果dim < 0，则划分的维度为rank(input) + dim。默认值为-1。
+    - **dim** (int|Tenspr，可选) - 整数或者形状为[1]的Tensor，数据类型为int32或int64。表示需要分割的维度。如果 ``dim < 0`` ，则划分的维度为 ``rank(input) + dim`` 。默认值为-1。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
 返回：分割后的Tensor列表。
 
-返回类型：列表(Variable(Tensor|LoDTensor))，数据类型为int32，int64，float32，float64。
 
 抛出异常：
-    - :code:`TypeError`：``num_or_sections`` 不是int、list 或 tuple。
-    - :code:`TypeError`：``dim`` 不是 int 或 Variable。
+    - :code:`TypeError`：``input`` 的数据类型不是bool、float16、float32、float64、int32或int64时 。
+    - :code:`TypeError`：``num_or_sections`` 不是int、list 或 tuple时。
+    - :code:`TypeError`：``dim`` 不是 int 或 Tensor时。当 ``dim`` 为Tensor，其数据类型不是int32或int64时。
 
 **代码示例**：
 
@@ -30,27 +30,31 @@ split
 
     import paddle.fluid as fluid
 
-    # 输入是维度为[3, 9, 5]的Tensor：
+    # input is a Tensor which shape is [3, 9, 5]
     input = fluid.data(
          name="input", shape=[3, 9, 5], dtype="float32")
 
-    # 传入num_or_sections为一个整数
-    x0, x1, x2 = fluid.layers.split(input, num_or_sections=3, dim=1)
-    x0.shape  # [3, 3, 5]
-    x1.shape  # [3, 3, 5]
-    x2.shape  # [3, 3, 5]
-
-    # 传入num_or_sections为一个整数列表
-    x0, x1, x2 = fluid.layers.split(input, num_or_sections=[2, 3, 4], dim=1)
-    x0.shape  # [3, 2, 5]
-    x1.shape  # [3, 3, 5]
-    x2.shape  # [3, 4, 5]
-
-    # 传入num_or_sections为一个整数列表，其中有一个元素为-1
-    x0, x1, x2 = fluid.layers.split(input, num_or_sections=[2, 3, -1], dim=1)
-    x0.shape  # [3, 2, 5]
-    x1.shape  # [3, 3, 5]
-    x2.shape  # [3, 4, 5]
+    out0, out1, out2 = fluid.layers.split(input, num_or_sections=3, dim=1)
+    # out0.shape [3, 3, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 3, 5]
+
+    out0, out1, out2 = fluid.layers.split(input, num_or_sections=[2, 3, 4], dim=1)
+    # out0.shape [3, 2, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 4, 5]
+
+    out0, out1, out2 = fluid.layers.split(input, num_or_sections=[2, 3, -1], dim=1)
+    # out0.shape [3, 2, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 4, 5]
+    
+    # dim is negative, the real dim is (rank(input) + axis) which real
+    # value is 1.
+    out0, out1, out2 = fluid.layers.split(input, num_or_sections=3, dim=-2)
+    # out0.shape [3, 3, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 3, 5]
 
 
 

doc/fluid/api_cn/tensor_cn/split_cn.rst

@@ -2,39 +2,55 @@
 split
 -------------------------------
 
-.. py:function:: paddle.tensor.split(input, num_or_sections, dim=-1, name=None)
-
-:alias_main: paddle.split
-:alias: paddle.split,paddle.tensor.split,paddle.tensor.manipulation.split
-:update_api: paddle.fluid.layers.split
+.. py:function:: paddle.tensor.split(x, num_or_sections, axis=0, name=None)
 
 
 
 该OP将输入Tensor分割成多个子Tensor。
 
 **参数**：
-       - **input** (Variable) - 输入变量，数据类型为float32，float64，int32，int64的多维Tensor或者LoDTensor。
-       - **num_or_sections** (int|list|tuple) - 如果 num_or_sections 是一个整数，则表示Tensor平均划分为相同大小子Tensor的数量。如果 num_or_sections 是一个list或tuple，那么它的长度代表子Tensor的数量，它的元素可以是整数或者形状为[1]的Tensor，依次代表子Tensor需要分割成的维度的大小。list或tuple的长度不能超过输入Tensor待分割的维度的大小。在list或tuple中，至多有一个元素值为-1，表示该值是由input的维度和其他num_or_sections中元素推断出来的。例如对一个维度为[4,6,6]Tensor的第三维进行分割时，指定num_or_sections=[2,-1,1]，输出的三个Tensor维度分别为：[4,6,2]，[4,6,3]，[4,6,1]。
-       - **dim** (int|Variable，可选) - 整数或者形状为[1]的Tensor，数据类型为int32或int64。表示需要分割的维度。如果dim < 0，则划分的维度为rank(input) + dim。默认值为-1。
-       - **name** (str，可选) - 一般无需设置，默认值为None。
+       - **x** (Tensor) - 输入变量，数据类型为bool, float16, float32，float64，int32，int64的多维Tensor。
+       - **num_or_sections** (int|list|tuple) - 如果 ``num_or_sections`` 是一个整数，则表示Tensor平均划分为相同大小子Tensor的数量。如果 ``num_or_sections`` 是一个list或tuple，那么它的长度代表子Tensor的数量，它的元素可以是整数或者形状为[1]的Tensor，依次代表子Tensor需要分割成的维度的大小。list或tuple的长度不能超过输入Tensor待分割的维度的大小。在list或tuple中，至多有一个元素值为-1，表示该值是由 ``x`` 的维度和其他 ``num_or_sections`` 中元素推断出来的。例如对一个维度为[4,6,6]Tensor的第三维进行分割时，指定 ``num_or_sections=[2,-1,1]`` ，输出的三个Tensor维度分别为：[4,6,2]，[4,6,3]，[4,6,1]。
+       - **axis** (int|Tensor，可选) - 整数或者形状为[1]的Tensor，数据类型为int32或int64。表示需要分割的维度。如果 ``axis < 0`` ，则划分的维度为 ``rank(x) + axis`` 。默认值为0。
+       - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
-**返回**：分割后的Tensor列表。
+返回：分割后的Tensor列表。
 
-**返回类型**：列表(Variable(Tensor|LoDTensor))，数据类型为int32，int64，float32，float64。
+抛出异常：
+    - :code:`TypeError`：``x`` 的数据类型不是float16、float32、float64、int32或int64时 。
+    - :code:`TypeError`：``num_or_sections`` 不是int、list 或 tuple时。
+    - :code:`TypeError`：``axis`` 不是 int 或 Tensor时。当 ``axis`` 为Tensor，其数据类型不是int32或int64时。
 
 **代码示例**：
 
 .. code-block:: python
 
-    import paddle
-    import paddle.fluid as fluid
     import numpy as np
-    with fluid.dygraph.guard():
-        input_1 = np.random.random([4, 6, 6]).astype("int32")
-        # input is a variable which shape is [4, 6, 6]
-        input = fluid.dygraph.to_variable(input_1)
-
-        x0, x1, x2 = paddle.split(input, num_or_sections= 3, dim=1)
-        # x0.shape [4, 2, 6]
-        # x1.shape [4, 2, 6]
-        # x2.shape [4, 2, 6]
+    import paddle
+    
+    paddle.enable_imperative()
+    # x is a Tensor which shape is [3, 9, 5]
+    x_np = np.random.random([3, 9, 5]).astype("int32")
+    x = paddle.imperative.to_variable(x_np)
+
+    out0, out1, out22 = paddle.split(x, num_or_sections=3, axis=1)
+    # out0.shape [3, 3, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 3, 5]
+
+    out0, out1, out2 = paddle.split(x, num_or_sections=[2, 3, 4], axis=1)
+    # out0.shape [3, 2, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 4, 5]
+
+    out0, out1, out2 = paddle.split(x, num_or_sections=[2, 3, -1], axis=1)
+    # out0.shape [3, 2, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 4, 5]
+    
+    # axis is negative, the real axis is (rank(x) + axis) which real
+    # value is 1.
+    out0, out1, out2 = paddle.split(x, num_or_sections=3, axis=-2)
+    # out0.shape [3, 3, 5]
+    # out1.shape [3, 3, 5]
+    # out2.shape [3, 3, 5]