paddle.nn.functional.softmax doc (#2334)

doc/fluid/api/nn/softmax.rst

+..  THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
+    !DO NOT EDIT THIS FILE MANUALLY!
+
 .. _api_nn_softmax:
 
 softmax
--------------------------------
-:doc_source: paddle.fluid.layers.softmax
+-------
 
+..  autofunction:: paddle.nn.functional.softmax
+    :noindex:
 

doc/fluid/api_cn/layers_cn/softmax_cn.rst

@@ -5,12 +5,6 @@ softmax
 
 .. py:function:: paddle.fluid.layers.softmax(input, use_cudnn=False, name=None, axis=-1)
 
-:alias_main: paddle.nn.functional.softmax
-:alias: paddle.nn.functional.softmax,paddle.nn.functional.activation.softmax
-:old_api: paddle.fluid.layers.softmax
-
-
-
 该OP实现了softmax层。OP的计算过程如下：
 
 步骤1：输入 ``input`` 的 ``axis`` 维会被置换到最后一维；

doc/fluid/api_cn/nn_cn/softmax_cn.rst

@@ -2,6 +2,118 @@
 
 softmax
 -------------------------------
-:doc_source: paddle.fluid.layers.softmax
+.. py:class:: paddle.nn.functional.softmax(x, axis=-1, name=None)
 
+该OP实现了softmax层。OP的计算过程如下：
 
+步骤1：输入 ``x`` 的 ``axis`` 维会被置换到最后一维；
+
+步骤2：将输入 ``x`` 在逻辑上变换为二维矩阵。二维矩阵第一维（列长度）是输入除最后一维之外的其他维度值的乘积，第二维（行长度）和输入 ``axis`` 维的长度相同；对于矩阵的每一行，softmax操作对其进行重新缩放，使得该行的每个元素在 \[0,1\] 范围内，并且总和为1；
+
+步骤3：softmax操作执行完成后，执行步骤1和步骤2的逆运算，将二维矩阵恢复至和输入 ``x`` 相同的维度。
+
+上述步骤2中softmax操作计算过程如下：
+
+    - 对于二维矩阵的每一行，计算K维向量（K是输入第 ``axis`` 维的长度）中指定位置的指数值和全部位置指数值的和。
+
+    - 指定位置指数值与全部位置指数值之和的比值就是softmax操作的输出。
+
+对于二维矩阵中的第i行和第j列有：
+
+.. math::
+
+
+    Out[i,j] = \frac{exp(X[i,j])}{\sum_j exp(X[i,j])}
+
+- 示例1（矩阵一共有三维。axis = -1，表示沿着最后一维（即第三维）做softmax操作）
+
+.. code-block:: python
+
+  输入
+
+    x.shape = [2, 3, 4] 
+
+    x.data = [[[2.0, 3.0, 4.0, 5.0],
+               [3.0, 4.0, 5.0, 6.0],
+               [7.0, 8.0, 8.0, 9.0]],
+              [[1.0, 2.0, 3.0, 4.0],
+               [5.0, 6.0, 7.0, 8.0],
+               [6.0, 7.0, 8.0, 9.0]]]
+
+    axis = -1
+
+  输出
+
+    out.shape = [2, 3, 4]
+
+    out.data = [[[0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+                 [0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+                 [0.07232949, 0.19661193, 0.19661193, 0.53444665]],
+                [[0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+                 [0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+                 [0.0320586 , 0.08714432, 0.23688282, 0.64391426]]]
+
+- 示例2（矩阵一共有三维。axis = 1，表示沿着第二维做softmax操作）
+
+.. code-block:: python
+
+  输入
+
+    x.shape = [2, 3, 4] 
+
+    x.data = [[[2.0, 3.0, 4.0, 5.0],
+               [3.0, 4.0, 5.0, 6.0],
+               [7.0, 8.0, 8.0, 9.0]],
+              [[1.0, 2.0, 3.0, 4.0],
+               [5.0, 6.0, 7.0, 8.0],
+               [6.0, 7.0, 8.0, 9.0]]]
+
+    axis = 1
+
+  输出
+
+    out.shape = [2, 3, 4]
+
+    out.data = [[[0.00657326, 0.00657326, 0.01714783, 0.01714783],
+                 [0.01786798, 0.01786798, 0.04661262, 0.04661262],
+                 [0.97555875, 0.97555875, 0.93623955, 0.93623955]],
+                [[0.00490169, 0.00490169, 0.00490169, 0.00490169],
+                 [0.26762315, 0.26762315, 0.26762315, 0.26762315],
+                 [0.72747516, 0.72747516, 0.72747516, 0.72747516]]] 
+
+
+参数
+::::::::::
+    - x (Tensor) - 输入的多维 ``Tensor`` ，数据类型为：float32、float64。
+    - axis (int, 可选) - 指定对输入 ``x`` 进行运算的轴。``axis`` 的有效范围是[-D, D)，D是输入 ``x`` 的维度， ``axis`` 为负值时与 :math:`axis + D` 等价。默认值为-1。
+    - name (str, 可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+返回
+::::::::::
+    ``Tensor`` ，数据类型和形状同 ``x`` 一致。
+
+代码示例
+::::::::::
+
+.. code-block:: python
+
+    import paddle
+    import paddle.nn.functional as F
+    import numpy as np
+
+    paddle.enable_imperative()
+
+    x = np.array([[[2.0, 3.0, 4.0, 5.0],
+                    [3.0, 4.0, 5.0, 6.0],
+                    [7.0, 8.0, 8.0, 9.0]],
+                    [[1.0, 2.0, 3.0, 4.0],
+                    [5.0, 6.0, 7.0, 8.0],
+                    [6.0, 7.0, 8.0, 9.0]]], 'float32')
+    x = paddle.imperative.to_variable(x)
+    out = F.softmax(x)
+    # [[[0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+    #   [0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+    #   [0.07232949, 0.19661193, 0.19661193, 0.53444665]],
+    # [[0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+    #   [0.0320586 , 0.08714432, 0.23688282, 0.64391426],
+    #   [0.0320586 , 0.08714432, 0.23688282, 0.64391426]]]