添加sparse路径，添加创建Sparse Tensor的文档 (#4646)

Author: zhangkaihuo

docs/api/gen_doc.py

@@ -472,6 +472,7 @@ def set_api_sketch():
         paddle.fft,
         paddle.version,
         paddle.profiler,
+        paddle.sparse,
     ]
 
     alldict = {}

docs/api/index_cn.rst

@@ -75,3 +75,5 @@ API 文档
 | paddle.vision                 | 视觉领域API，包括 数据集 Cifar10 、数据处理           |
 |                               | ColorJitter、常用基础网络结构 ResNet 等。             |
 +-------------------------------+-------------------------------------------------------+
+| paddle.sparse                 | 稀疏领域的API。                                       |
++-------------------------------+-------------------------------------------------------+

docs/api/index_en.rst

@@ -84,4 +84,6 @@ In this version, PaddlePaddle has made many optimizations to the APIs. You can r
 |                               | data processing ColorJitter, and commonly used models |
 |                               | like resnet                                           |
 +-------------------------------+-------------------------------------------------------+
+| paddle.sparse                 | The Sparse domain API.                                |
++-------------------------------+-------------------------------------------------------+
 

docs/api/paddle/Overview_cn.rst

@@ -18,6 +18,7 @@ paddle 目录下包含tensor、device、framework相关API以及某些高层API
 -  :ref:`framework相关 <about_framework>`
 -  :ref:`device相关 <about_device>`
 -  :ref:`高层API相关 <about_hapi>`
+-  :ref:`稀疏API相关 <about_sparse_api>`
 
 
 
@@ -386,3 +387,15 @@ device相关
     " :ref:`paddle.Model <cn_api_paddle_Model>` ", "一个具备训练、测试、推理的神经网络"
     " :ref:`paddle.summary <cn_api_paddle_summary>` ", "打印网络的基础结构和参数信息"
     " :ref:`paddle.flops <cn_api_paddle_flops>` ", "打印网络的基础结构和参数信息"
+
+.. _about_sparse_api:
+
+稀疏API相关
+::::::::::::::::::::
+
+.. csv-table::
+    :header: "API名称", "API功能"
+    :widths: 10, 30
+
+    " :ref:`paddle.sparse.sparse_coo_tensor<cn_api_paddle_sparse_coo_tensor>` ", "创建一个COO(Coordinate)格式的稀疏Tensor"
+    " :ref:`paddle.sparse.sparse_csr_tensor<cn_api_paddle_sparse_csr_tensor>` ", "创建一个CSR(Compressed Sparse Row)格式的稀疏Tensor"

docs/api/paddle/sparse/sparse_coo_tensor_cn.rst

@@ -0,0 +1,43 @@
+.. _cn_api_paddle_sparse_coo_tensor:
+
+sparse_coo_tensor
+-------------------------------
+
+
+.. py:function:: paddle.sparse.sparse_coo_tensor(indices, values, shape=None, dtype=None, place=None, stop_gradient=True)
+
+该API通过已知的非零元素的 ``indices`` 和 ``values`` 来创建一个coordinate格式的稀疏tensor，tensor类型为 ``paddle.Tensor`` 。
+
+其中 ``indices`` 是存放坐标信息，是一个二维数组，每一列是对应非零元素的坐标，shape是 ``[sparse_dim, nnz]`` , ``sparse_dim`` 是坐标的维度， ``nnz`` 是非零元素的个数。
+
+其中 ``values`` 是存放非零元素，是一个多维数组，shape是 ``[nnz, {dense_dim}]`` , nnz是非零元素个数， ``dense_dim`` 是非零元素的维度。
+
+
+如果 ``values`` 已经是一个tensor，且 ``dtype`` 、 ``place`` 没有发生变化，将不会发生 tensor 的拷贝并返回原来的 tensor。
+否则会创建一个新的tensor，且不保留原来计算图。
+
+参数
+:::::::::
+
+    - **indices** (list|tuple|ndarray|Tensor) - 初始化tensor的数据，可以是
+      list，tuple，numpy\.ndarray，paddle\.Tensor类型。
+    - **values** (list|tuple|ndarray|Tensor) - 初始化tensor的数据，可以是
+      list，tuple，numpy\.ndarray，paddle\.Tensor类型。
+    - **shape** (list|tuple, optional) - 稀疏Tensor的形状，也是Tensor的形状，如果没有提供，将自动推测出最小的形状。
+    - **dtype** (str|np.dtype, optional) - 创建tensor的数据类型，可以是 'bool' ，'float16'，'float32'，
+      'float64' ，'int8'，'int16'，'int32'，'int64'，'uint8'，'complex64'，'complex128'。
+      默认值为None，如果 ``values`` 为python浮点类型，则从
+      :ref:`cn_api_paddle_framework_get_default_dtype` 获取类型，如果 ``values`` 为其他类型，
+      则会自动推导类型。
+    - **place** (CPUPlace|CUDAPinnedPlace|CUDAPlace|str, optional) - 创建tensor的设备位置，可以是 
+      CPUPlace, CUDAPinnedPlace, CUDAPlace。默认值为None，使用全局的place。
+    - **stop_gradient** (bool, optional) - 是否阻断Autograd的梯度传导。默认值为True，此时不进行梯度传传导。
+
+返回
+:::::::::
+通过 ``indices`` 和 ``values`` 创建的稀疏Tensor。
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.sparse.sparse_coo_tensor

docs/api/paddle/sparse/sparse_csr_tensor_cn.rst

@@ -0,0 +1,46 @@
+.. _cn_api_paddle_sparse_csr_tensor:
+
+sparse_csr_tensor
+-------------------------------
+
+
+.. py:function:: paddle.sparse.sparse_csr_tensor(crows, cols, values, shape, dtype=None, place=None, stop_gradient=True)
+
+该API通过已知的非零元素的 ``crows`` , ``cols`` 和 ``values`` 来创建一个CSR(Compressed Sparse Row) 格式的稀疏tensor，tensor类型为 ``paddle.Tensor`` 。
+
+当前 ``sparse_csr_tensor`` 要求输入的 ``crows`` 中每个batch的数据是递增的， ``cols`` 也是递增的。
+
+``crows`` 可以是 scalar，tuple，list，numpy\.ndarray，paddle\.Tensor。
+``cols`` 可以是 scalar，tuple，list，numpy\.ndarray，paddle\.Tensor。
+``values`` 可以是 scalar，tuple，list，numpy\.ndarray，paddle\.Tensor。
+
+
+如果 ``values`` 已经是一个tensor，且 ``dtype`` 、 ``place`` 没有发生变化，将不会发生 tensor 的拷贝并返回原来的 tensor。
+否则会创建一个新的tensor，且不保留原来计算图。
+
+参数
+:::::::::
+
+    - **crows** (list|tuple|ndarray|Tensor) - 每行第一个非零元素在 ``values`` 的起始位置。可以是
+      list，tuple，numpy\.ndarray，paddle\.Tensor类型。
+    - **cols** (list|tuple|ndarray|Tensor) - 一维数组，存储每个非零元素的列信息。可以是
+      list，tuple，numpy\.ndarray，paddle\.Tensor类型。
+    - **values** (list|tuple|ndarray|Tensor) - 一维数组，存储非零元素，可以是
+      list，tuple，numpy\.ndarray，paddle\.Tensor类型。
+    - **shape** (list|tuple) - 稀疏Tensor的形状，也是Tensor的形状，如果没有提供，将自动推测出最小的形状。
+    - **dtype** (str|np.dtype, optional) - 创建tensor的数据类型，可以是 'bool' ，'float16'，'float32'，
+      'float64' ，'int8'，'int16'，'int32'，'int64'，'uint8'，'complex64'，'complex128'。
+      默认值为None，如果 ``values`` 为python浮点类型，则从
+      :ref:`cn_api_paddle_framework_get_default_dtype` 获取类型，如果 ``values`` 为其他类型，
+      则会自动推导类型。
+    - **place** (CPUPlace|CUDAPinnedPlace|CUDAPlace|str, optional) - 创建tensor的设备位置，可以是 
+      CPUPlace, CUDAPinnedPlace, CUDAPlace。默认值为None，使用全局的place。
+    - **stop_gradient** (bool, optional) - 是否阻断Autograd的梯度传导。默认值为True，此时不进行梯度传传导。
+
+返回
+:::::::::
+通过 ``crows``, ``cols`` 和 ``values`` 创建的稀疏Tensor。
+
+**代码示例**
+
+COPY-FROM: paddle.sparse.sparse_csr_tensor