【PaddlePaddle Hackathon 3 No.20】为 Paddle 新增 vsplit API (#5213)

* add docs of paddle.vsplit

* update

* Update docs/api/paddle/vsplit_cn.rst

Co-authored-by: Nyakku Shigure <[email protected]>

* update description of x

* remove extra whitespace

Co-authored-by: Nyakku Shigure <[email protected]>

docs/api/api_label

@@ -237,6 +237,7 @@ paddle.sinh	.. _api_paddle_sinh:
 paddle.slice	.. _api_paddle_slice:
 paddle.sort	.. _api_paddle_sort:
 paddle.split	.. _api_paddle_split:
+paddle.vsplit	.. _api_paddle_vsplit:
 paddle.sqrt	.. _api_paddle_sqrt:
 paddle.Tensor.sqrt_	.. _api_paddle_Tensor_sqrt_:
 paddle.square	.. _api_paddle_square:

docs/api/paddle/Overview_cn.rst

@@ -316,7 +316,8 @@ tensor 元素操作相关（如：转置，reshape 等）
     " :ref:`paddle.scatter_nd_add <cn_api_fluid_layers_scatter_nd_add>` ", "通过对 Tensor 中的单个值或切片应用稀疏加法，从而得到输出的 Tensor"
     " :ref:`paddle.shard_index <cn_api_fluid_layers_shard_index>` ", "根据分片（shard）的偏移量重新计算分片的索引"
     " :ref:`paddle.slice <cn_api_paddle_slice>` ", "沿多个轴生成 input 的切片"
-    " :ref:`paddle.split <cn_api_distributed_split>` ", "将输入 Tensor 分割成多个子 Tensor"
+    " :ref:`paddle.split <cn_api_paddle_tensor_split>` ", "将输入 Tensor 分割成多个子 Tensor"
+    " :ref:`paddle.vsplit <cn_api_paddle_tensor_vsplit>` ", "将输入 Tensor 沿第一个维度分割成多个子 Tensor"
     " :ref:`paddle.squeeze <cn_api_paddle_tensor_squeeze>` ", "删除输入 Tensor 的 Shape 中尺寸为 1 的维度"
     " :ref:`paddle.squeeze_ <cn_api_paddle_tensor_squeeze_>` ", "Inplace 版本的 squeeze API，对输入 x 采用 Inplace 策略"
     " :ref:`paddle.stack <cn_api_paddle_tensor_stack>` ", "沿 axis 轴对输入 x 进行堆叠操作"

docs/api/paddle/Tensor/Overview_en.rst

@@ -234,6 +234,7 @@ Methods
     solve
     sort
     split
+    vsplit
     sqrt
     sqrt_
     square

docs/api/paddle/Tensor_cn.rst

@@ -2059,6 +2059,15 @@ split(num_or_sections, axis=0, name=None)
 
 请参考 :ref:`cn_api_fluid_layers_split`
 
+vsplit(num_or_sections, name=None)
+:::::::::
+
+返回：计算后的 Tensor
+
+返回类型：Tensor
+
+请参考 :ref:`cn_api_paddle_tensor_vsplit`
+
 sqrt(name=None)
 :::::::::
 

docs/api/paddle/vsplit_cn.rst

@@ -0,0 +1,27 @@
+.. _cn_api_paddle_tensor_vsplit:
+
+vsplit
+-------------------------------
+
+.. py:function:: paddle.vsplit(x, num_or_sections, name=None)
+
+
+
+将输入 Tensor 沿着垂直轴分割成多个子 Tensor，等价于将 paddle.split API 的参数 axis 固定为 0。
+
+参数
+:::::::::
+       - **x** (Tensor) - 输入变量，数据类型为 bool、float16、float32、float64、uint8、int8、int32、int64 的多维 Tensor，其维度必须大于 1。
+       - **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`` 中元素推断出来的。
+       - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+:::::::::
+
+list[Tensor]，分割后的 Tensor 列表。
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.vsplit