add cn doc of trace API & diag_embed API (#2039)

* add cn doc of trace API

* add cn doc of diag_embed API

doc/fluid/api_cn/nn_cn/diag_embed_cn.rst

-diag
+.. _cn_api_functional_diag_embed:
+
+diag_embed
 -------------------------------
-**版本升级，文档正在开发中**
+
+.. py:function:: paddle.functional.diag_embed(input, offset=0, dim1=-2, dim2=-1):
+
+    该 OP 创建一个 Tensor，其在指定的 2D 平面（由 ``dim1`` 和 ``dim2`` 指定）上的对角线由输入 ``input`` 填充。
+    默认的，指定的 2D 平面由返回 Tensor 的最后两维组成。
+    
+    参数 ``offset`` 确定在指定的二维平面中填充对角线的位置：
+
+    - 如果 offset = 0，则填充主对角线。
+    - 如果 offset > 0，则填充主对角线右上的对角线。
+    - 如果 offset < 0，则填充主对角线左下的对角线。
+
+参数：
+    - **input** （Variable|numpy.ndarray）- 输入变量，至少为 1D 数组，支持数据类型为 float32，float64，int32，int64。
+    - **offset** （int ，可选）- 从指定的二维平面中获取对角线的位置，默认值为 0，既主对角线。
+    - **dim1** （int ， 可选）- 填充对角线的二维平面的第一维，默认值为 -2。
+    - **dim2** （int ， 可选）- 填充对角线的二维平面的第二维，默认值为 -1。
+
+返回： 指定二维平面填充了对角线的 Tensor。数据类型和输入数据类型一致。
+
+返回类型：  变量（Variable）
+
+**代码示例** 
+
+..  code-block:: python
+
+    import paddle.nn.functional as F
+    import paddle.fluid.dygraph as dg
+    import numpy as np
+    
+    diag_embed = np.random.randn(2, 3).astype('float32')
+    # [[ 0.7545889 , -0.25074545,  0.5929117 ],
+    #  [-0.6097662 , -0.01753256,  0.619769  ]]
+    with dg.guard():
+        data1 = F.diag_embed(diag_embed)
+        data1.numpy()
+        # [[[ 0.7545889 ,  0.        ,  0.        ],
+        #  [ 0.        , -0.25074545,  0.        ],
+        #   [ 0.        ,  0.        ,  0.5929117 ]],
+
+        # [[-0.6097662 ,  0.        ,  0.        ],
+        #  [ 0.        , -0.01753256,  0.        ],
+        #  [ 0.        ,  0.        ,  0.619769  ]]]
+
+        data2 = F.diag_embed(diag_embed, offset=-1, dim1=0, dim2=2)
+        data2.numpy()
+        # [[[ 0.        ,  0.        ,  0.        ,  0.        ],
+        #   [ 0.7545889 ,  0.        ,  0.        ,  0.        ],
+        #   [ 0.        , -0.25074545,  0.        ,  0.        ],
+        #   [ 0.        ,  0.        ,  0.5929117 ,  0.        ]],
+        #
+        #  [[ 0.        ,  0.        ,  0.        ,  0.        ],
+        #   [-0.6097662 ,  0.        ,  0.        ,  0.        ],
+        #   [ 0.        , -0.01753256,  0.        ,  0.        ],
+        #   [ 0.        ,  0.        ,  0.619769  ,  0.        ]]]
+
+        data3 = F.diag_embed(diag_embed, offset=1, dim1=0, dim2=2)
+        data3.numpy()
+        # [[[ 0.        ,  0.7545889 ,  0.        ,  0.        ],
+        #   [ 0.        , -0.6097662 ,  0.        ,  0.        ]],
+        #
+        #  [[ 0.        ,  0.        , -0.25074545,  0.        ],
+        #   [ 0.        ,  0.        , -0.01753256,  0.        ]],
+        #
+        #  [[ 0.        ,  0.        ,  0.        ,  0.5929117 ],
+        #   [ 0.        ,  0.        ,  0.        ,  0.619769  ]],
+        #
+        #  [[ 0.        ,  0.        ,  0.        ,  0.        ],
+        #   [ 0.        ,  0.        ,  0.        ,  0.        ]]]

doc/fluid/api_cn/tensor_cn.rst

@@ -68,6 +68,7 @@ paddle.tensor
     tensor_cn/tanh_cn.rst
     tensor_cn/t_cn.rst
     tensor_cn/tensordot_cn.rst
+    tensor_cn/trace_cn.rst
     tensor_cn/transpose_cn.rst
     tensor_cn/tril_cn.rst
     tensor_cn/triu_cn.rst

doc/fluid/api_cn/tensor_cn/trace_cn.rst

+.. _cn_api_tensor_trace:
+
+trace
+-------------------------------
+
+.. py:function:: paddle.trace(input, offset=0, dim1=0, dim2=1)
+
+该 OP 计算输入 Tensor 在指定平面上的对角线元素之和，并输出相应的计算结果。
+
+如果输入是 2D Tensor，则返回对角线元素之和。 
+
+如果输入的维度大于 2D，则返回一个由对角线元素之和组成的数组，其中对角线从由 dim1 和 dim2 指定的二维平面中获得。默认由输入的前两维组成获得对角线的 2D 平面。
+
+参数 ``offset`` 确定从指定的二维平面中获取对角线的位置：
+
+    - 如果 offset = 0，则取主对角线。
+    - 如果 offset > 0，则取主对角线右上的对角线。
+    - 如果 offset < 0，则取主对角线左下的对角线。
+
+参数：
+    - **input** （Variable）- 输入变量，至少为 2D 数组，支持数据类型为 float32，float64，int32，int64。
+    - **offset** （int ，可选）- 从指定的二维平面中获取对角线的位置，默认值为 0，既主对角线。
+    - **dim1** （int ， 可选）- 获取对角线的二维平面的第一维，默认值为 0。
+    - **dim2** （int ， 可选）- 获取对角线的二维平面的第二维，默认值为 1。
+
+返回： 指定二维平面的对角线元素之和。数据类型和输入数据类型一致。
+
+返回类型：  变量（Variable）
+
+**代码示例**
+
+..  code-block:: python
+
+    import paddle.tensor as tensor
+    import paddle.fluid.dygraph as dg
+    import numpy as np
+            
+    case1 = np.random.randn(2, 3).astype('float32')
+    case2 = np.random.randn(3, 10, 10).astype('float32')
+    case3 = np.random.randn(3, 10, 5, 10).astype('float32')
+            
+    with dg.guard():
+        case1 = dg.to_variable(case1)
+        case2 = dg.to_variable(case2)
+        case3 = dg.to_variable(case3)
+        data1 = tensor.trace(case1) # data1.shape = [1]
+        data2 = tensor.trace(case2, offset=1, dim1=1, dim2=2) # data2.shape = [3]
+        data3 = tensor.trace(case3, offset=-3, dim1=1, dim2=-1) # data2.shape = [3, 5]