normal, standard_normal docs; test=develop (#2406)

doc/fluid/api/tensor/random.rst

@@ -5,8 +5,10 @@ random
 ..  toctree::
     :maxdepth: 1
 
+    random/normal.rst
     random/rand.rst
     random/randint.rst
     random/randn.rst
     random/randperm.rst
+    random/standard_normal.rst
     random/uniform.rst

doc/fluid/api/tensor/random/normal.rst

+..  THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
+    !DO NOT EDIT THIS FILE MANUALLY!
+
+.. _api_tensor_random_normal:
+
+normal
+------
+
+..  autofunction:: paddle.tensor.random.normal
+    :noindex:
+

doc/fluid/api/tensor/random/standard_normal.rst

+..  THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
+    !DO NOT EDIT THIS FILE MANUALLY!
+
+.. _api_tensor_random_standard_normal:
+
+standard_normal
+---------------
+
+..  autofunction:: paddle.tensor.random.standard_normal
+    :noindex:
+

doc/fluid/api_cn/paddle_cn.rst

@@ -108,6 +108,7 @@ paddle
 	paddle_cn/name_scope_cn.rst
 	paddle_cn/no_grad_cn.rst
 	paddle_cn/nonzero_cn.rst
+	paddle_cn/normal_cn.rst
 	paddle_cn/not_equal_cn.rst
 	paddle_cn/numel_cn.rst
 	paddle_cn/ones_cn.rst
@@ -155,6 +156,7 @@ paddle
 	paddle_cn/square_cn.rst
 	paddle_cn/squeeze_cn.rst
 	paddle_cn/stack_cn.rst
+	paddle_cn/standard_normal.rst
 	paddle_cn/stanh_cn.rst
 	paddle_cn/std_cn.rst
 	paddle_cn/strided_slice_cn.rst

doc/fluid/api_cn/paddle_cn/normal_cn.rst

+.. _cn_api_paddle_cn_normal:
+
+normal
+-------------------------------
+:doc_source: paddle.tensor.normal
+
+

doc/fluid/api_cn/paddle_cn/standard_normal_cn.rst

+.. _cn_api_paddle_cn_standard_normal:
+
+standard_normal
+-------------------------------
+:doc_source: paddle.tensor.standard_normal
+
+

doc/fluid/api_cn/tensor_cn.rst

@@ -103,6 +103,7 @@ paddle.tensor
     tensor_cn/multiplex_cn.rst
     tensor_cn/nonzero_cn.rst
     tensor_cn/norm_cn.rst
+    tensor_cn/normal_cn.rst
     tensor_cn/not_equal_cn.rst
     tensor_cn/numel_cn.rst
     tensor_cn/ones_cn.rst
@@ -144,6 +145,7 @@ paddle.tensor
     tensor_cn/square_cn.rst
     tensor_cn/squeeze_cn.rst
     tensor_cn/stack_cn.rst
+    tensor_cn/standard_normal_cn.rst
     tensor_cn/stanh_cn.rst
     tensor_cn/std_cn.rst
     tensor_cn/strided_slice_cn.rst

doc/fluid/api_cn/tensor_cn/normal_cn.rst

+.. _cn_api_tensor_normal:
+
+normal
+-------------------------------
+
+.. py:function:: paddle.normal(mean=0.0, std=1.0, shape=None, name=None)
+
+
+该OP返回符合正态分布（均值为 ``mean`` ，标准差为 ``std`` 的正态随机分布）的随机Tensor。
+
+如果 ``mean`` 是Tensor，则输出Tensor和 ``mean`` 具有相同的形状和数据类型。
+如果 ``mean`` 不是Tensor，且 ``std`` 是Tensor，则输出Tensor和 ``std`` 具有相同的形状和数据类型。
+如果 ``mean`` 和 ``std`` 都不是Tensor，则输出Tensor的形状为 ``shape``，数据类型为float32。
+
+如果 ``mean`` 和 ``std`` 都是Tensor，则 ``mean`` 和 ``std`` 的元素个数应该相同。
+
+参数
+::::::::::
+    - mean (float|Tensor, 可选) - 输出Tensor的正态分布的平均值。如果 ``mean`` 是float，则表示输出Tensor中所有元素的正态分布的平均值。如果 ``mean`` 是Tensor(支持的数据类型为float32、float64)，则表示输出Tensor中每个元素的正态分布的平均值。默认值为0.0
+    - std (float|Tensor, 可选) - 输出Tensor的正态分布的标准差。如果 ``std`` 是float，则表示输出Tensor中所有元素的正态分布的标准差。如果 ``std`` 是Tensor(支持的数据类型为float32、float64)，则表示输出Tensor中每个元素的正态分布的标准差。默认值为0.0
+    - shape (list|tuple|Tensor, 可选) - 生成的随机Tensor的形状。如果 ``shape`` 是list、tuple，则其中的元素可以是int，或者是形状为[1]且数据类型为int32、int64的Tensor。如果 ``shape`` 是Tensor，则是数据类型为int32、int64的1-D Tensor。如果 ``mean`` 或者 ``std`` 是Tensor，输出Tensor的形状和 ``mean`` 或者 ``std`` 相同(此时 ``shape`` 无效)。默认值为None。
+    - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+返回
+::::::::::
+  Tensor：符合正态分布（均值为 ``mean`` ，标准差为 ``std`` 的正态随机分布）的随机Tensor。
+
+示例代码
+::::::::::
+
+.. code-block:: python
+
+    import paddle
+    import numpy as np
+
+    paddle.disable_static()
+
+    out1 = paddle.normal(shape=[2, 3])
+    # [[ 0.17501129  0.32364586  1.561118  ]
+    #  [-1.7232178   1.1545963  -0.76156676]]
+
+    mean_tensor = paddle.to_tensor(np.array([1.0, 2.0, 3.0]))
+    out2 = paddle.normal(mean=mean_tensor)
+    # [ 0.18644847 -1.19434458  3.93694787]
+
+    std_tensor = paddle.to_tensor(np.array([1.0, 2.0, 3.0]))
+    out3 = paddle.normal(mean=mean_tensor, std=std_tensor)
+    # [1.00780561 3.78457445 5.81058198]

doc/fluid/api_cn/tensor_cn/standard_normal_cn.rst

+.. _cn_api_tensor_random_standard_normal:
+
+standard_normal
+-------------------------------
+
+.. py:function:: paddle.standard_normal(shape, dtype=None, name=None)
+
+
+该OP返回符合标准正态分布（均值为0，标准差为1的正态随机分布）的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。
+
+参数
+::::::::::
+  - **shape** (list|tuple|Tensor) - 生成的随机Tensor的形状。如果 ``shape`` 是list、tuple，则其中的元素可以是int，或者是形状为[1]且数据类型为int32、int64的Tensor。如果 ``shape`` 是Tensor，则是数据类型为int32、int64的1-D Tensor。
+  - **dtype** (str|np.dtype|core.VarDesc.VarType, 可选) - 输出Tensor的数据类型，支持float32、float64。当该参数值为None时， 输出Tensor的数据类型为float32。默认值为None.
+  - **name** (str, 可选) - 输出的名字。一般无需设置，默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。
+
+返回
+::::::::::
+  Tensor：符合标准正态分布的随机Tensor，形状为 ``shape``，数据类型为 ``dtype``。
+
+抛出异常
+::::::::::
+  - ``TypeError`` - 如果 ``shape`` 的类型不是list、tuple、Tensor。
+  - ``TypeError`` - 如果 ``dtype`` 不是float32、float64。
+
+示例代码
+::::::::::
+
+.. code-block:: python
+
+    import paddle
+    import numpy as np
+
+    paddle.disable_static()
+
+    # example 1: attr shape is a list which doesn't contain Tensor.
+    result_1 = paddle.standard_normal(shape=[2, 3])
+    # [[-2.923464  ,  0.11934398, -0.51249987],
+    #  [ 0.39632758,  0.08177969,  0.2692008 ]]
+
+    # example 2: attr shape is a list which contains Tensor.
+    dim_1 = paddle.fill_constant([1], "int64", 2)
+    dim_2 = paddle.fill_constant([1], "int32", 3)
+    result_2 = paddle.standard_normal(shape=[dim_1, dim_2, 2])
+    # [[[-2.8852394 , -0.25898588],
+    #   [-0.47420555,  0.17683524],
+    #   [-0.7989969 ,  0.00754541]],
+    #  [[ 0.85201347,  0.32320443],
+    #   [ 1.1399018 ,  0.48336947],
+    #   [ 0.8086993 ,  0.6868893 ]]]
+
+    # example 3: attr shape is a Tensor, the data type must be int64 or int32.
+    var_shape = paddle.to_tensor(np.array([2, 3]))
+    result_3 = paddle.standard_normal(var_shape)
+    # [[-2.878077 ,  0.17099959,  0.05111201]
+    #  [-0.3761474, -1.044801  ,  1.1870178 ]]