modify doc for Attr(data_format) or Attr(data_layout) and add Raises information (#1592)

* modify doc for Attr(data_format) or Attr(data_layout) and add Raises information, test=develop

* modify doc of conv3d_transpose for Raises information, test=develop

doc/fluid/api_cn/layers_cn/affine_channel_cn.rst

@@ -13,7 +13,7 @@ affine_channel
   - **x** (Variable): 特征图输入可以是一个具有NCHW格式或NHWC格式的的4-D张量。它也可以是二维张量，此时该算法应用于第二维度的仿射变换。数据类型为float32或float64。
   - **scale** (Variable): 维度为(C)的一维输入，第C个元素为输入的第C通道仿射变换的尺度因子。数据类型为float32或float64。
   - **bias** (Variable): 维度为(C)的一维输入，第C个元素是输入的第C个通道的仿射变换的偏置。数据类型为float32或float64。
-  - **data_layout** (str，可选): NCHW 或 NHWC，如果输入是一个2D张量，可以忽略该参数，默认值为"NCHW"。
+  - **data_layout** (str，可选): 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。如果输入是一个2D张量，可以忽略该参数，默认值为"NCHW"。
   - **name** (str，可选): 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
   - **act** (str，可选): 应用于该层输出的激活函数，默认值为None。
 

doc/fluid/api_cn/layers_cn/batch_norm_cn.rst

@@ -45,7 +45,7 @@ moving_mean和moving_var是训练过程中统计得到的全局均值和方差
     - **epsilon** （float）- 加在分母上为了数值稳定的值。默认：1e-5。
     - **param_attr** (ParamAttr|None) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。batch_norm算子默认的权重初始化是1.0。
     - **bias_attr** （ParamAttr|None）- 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。batch_norm算子默认的偏置初始化是0.0。
-    - **data_layout** （string) - 指定输入数据格式，数据格式可以为NCHW或者NHWC。默认：NCHW。
+    - **data_layout** （string) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
     - **in_place** （bool）- batch_norm的输出复用输入的tensor，可以节省显存。默认：False。
     - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
     - **moving_mean_name** （string）- moving_mean的名称，存储全局均值。如果将其设置为None, ``batch_norm`` 将随机命名全局均值；否则， ``batch_norm`` 将命名全局均值为 ``moving_mean_name`` 。默认：None。

doc/fluid/api_cn/layers_cn/conv2d_cn.rst

@@ -69,7 +69,7 @@ conv2d
     - **use_cudnn** （bool，可选）- 是否使用cudnn内核。只有已安装cudnn库时才有效。默认值：True。
     - **act** (str，可选) - 激活函数类型， 如tanh、softmax、sigmoid，relu等，支持列表请参考 :ref:`api_guide_activations` 。如果设为None，则未添加激活函数。默认值：None。
     - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。
-    - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
+    - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
 
 返回：4-D Tensor，数据类型与 ``input`` 一致。如果未指定激活层，则返回卷积计算的结果，如果指定激活层，则返回卷积和激活计算之后的最终结果。
 
@@ -81,6 +81,10 @@ conv2d
     - ``ValueError`` - 如果 ``input`` 的通道数未被明确定义。
     - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。
     - ``ValueError`` - 如果 ``padding`` 含有4个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。
+    - ``ShapeError`` - 如果输入不是4-D Tensor。
+    - ``ShapeError`` - 如果输入和滤波器的维度大小不相同。
+    - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。
+    - ``ShapeError`` - 如果输出的通道数不能被 ``groups`` 整除。
 
 
 **代码示例**：

doc/fluid/api_cn/layers_cn/conv2d_transpose_cn.rst

@@ -80,7 +80,7 @@ conv2d_transpose
   - **use_cudnn** (bool，可选) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认：True。
   - **act** (str，可选) -  激活函数类型，如果设置为None，则不使用激活函数。默认：None。
   - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
-  - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
+  - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
 
 返回：4-D Tensor，数据类型与 ``input`` 一致。如果未指定激活层，则返回转置卷积计算的结果，如果指定激活层，则返回转置卷积和激活计算之后的最终结果。
 
@@ -91,6 +91,10 @@ conv2d_transpose
     -  ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。
     -  ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。
     -  ``ValueError`` - 如果 ``padding`` 含有4个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。
+    -  ``ValueError`` - 如果 ``output_size`` 和 ``filter_size`` 同时为None。
+    -  ``ShapeError`` - 如果输入不是4-D Tensor。
+    -  ``ShapeError`` - 如果输入和滤波器的维度大小不相同。
+    -  ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。
 
 **代码示例**
 

doc/fluid/api_cn/layers_cn/conv3d_cn.rst

@@ -74,7 +74,7 @@ conv3d
     - **use_cudnn** （bool，可选）- 是否使用cudnn内核。只有已安装cudnn库时才有效。默认值：True。
     - **act** (str，可选) - 激活函数类型， 如tanh、softmax、sigmoid，relu等，支持列表请参考 :ref:`api_guide_activations` 。如果设为None，则未添加激活函数。默认值：None。
     - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。
-    - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。默认值："NCDHW"。
+    - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。默认值："NCDHW"。
 
 返回：5-D Tensor，数据类型与 ``input`` 一致。如果未指定激活层，则返回卷积计算的结果，如果指定激活层，则返回卷积和激活计算之后的最终结果。
 
@@ -86,6 +86,10 @@ conv3d
     - ``ValueError`` - 如果 ``input`` 的通道数未被明确定义。
     - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。
     - ``ValueError`` - 如果 ``padding`` 含有5个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。
+    - ``ShapeError`` - 如果输入不是5-D Tensor。
+    - ``ShapeError`` - 如果输入和滤波器的维度大小不相同。
+    - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。
+    - ``ShapeError`` - 如果输出的通道数不能被 ``groups`` 整除。
 
 
 **代码示例**：

doc/fluid/api_cn/layers_cn/conv3d_transpose_cn.rst

@@ -86,17 +86,21 @@ conv3d_transpose
   - **use_cudnn** (bool，可选) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认：True。
   - **act** (str，可选) -  激活函数类型，如果设置为None，则不使用激活函数。默认：None。
   - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
-  - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCDHW"。
+  - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCDHW"。
 
 返回：5-D Tensor，数据类型与 ``input`` 一致。如果未指定激活层，则返回转置卷积计算的结果，如果指定激活层，则返回转置卷积和激活计算之后的最终结果。
 
 返回类型：Variable
 
 抛出异常:
-    - ``ValueError``  : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError
-    - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。
+    - ``ValueError`` - 如果输入的shape、filter_size、stride、padding和groups不匹配。
+    - ``ValueError`` - 如果 ``data_format`` 既不是"NCDHW"也不是"NDHWC"。
     - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。
     - ``ValueError`` - 如果 ``padding`` 含有5个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。
+    - ``ValueError`` - 如果 ``output_size`` 和 ``filter_size`` 同时为None。
+    - ``ShapeError`` - 如果输入不是5-D Tensor。
+    - ``ShapeError`` - 如果输入和滤波器的维度大小不相同。
+    - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。
 
 **代码示例**
 

doc/fluid/api_cn/layers_cn/data_norm_cn.rst

@@ -28,7 +28,7 @@ data_norm
   - **act** （string，默认None） - 激活函数类型，线性| relu | prelu | ...
   - **epsilon** （float，默认1e-05） -
   - **param_attr** （ParamAttr） - 参数比例的参数属性。
-  - **data_layout** （string，默认NCHW） -  NCHW | NHWC
+  - **data_layout** （str，可选） -  指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
   - **in_place** （bool，默认值False） - 使data_norm的输入和输出复用同一块内存。
   - **name** （string，默认None） - 此层的名称（可选）。 如果设置为None，则将自动命名该层。
   - **moving_mean_name** （string，Default None） - 存储全局Mean的moving_mean的名称。

doc/fluid/api_cn/layers_cn/group_norm_cn.rst

@@ -14,7 +14,7 @@ group_norm
   - **param_attr** (ParamAttr|bool，可选) ：指定权重参数属性的对象。若 ``param_attr`` 为bool类型，只支持为False，表示没有权重参数。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
   - **bias_attr** (ParamAttr|bool，可选) : 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
   - **act** (str，可选)：将激活应用于输出的 group normalizaiton。
-  - **data_layout** (str，可选)：输入和输出的数据格式，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
+  - **data_layout** (str，可选)：指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
   - **name** (str，可选)：具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
 返回：4-D Tensor，数据类型和格式与 `input` 一致。
@@ -23,6 +23,9 @@ group_norm
 
 抛出异常：
     - ``ValueError`` - 如果 ``data_layout`` 既不是"NCHW"也不是"NHWC"。
+    - ``ValueError`` - 如果 ``groups`` 小于1，或者 ``groups`` 大于输入的通道数。
+    - ``ShapeError`` - 如果  ``param_attr`` (Scale) 或者 ``bias_attr`` (Bias) 不是 1-D Tensor。
+    - ``ShapeError`` - 如果  ``param_attr`` (Scale) 或者 ``bias_attr`` (Bias) 的大小与输入的通道数不相等。
 
 **代码示例：**
 

doc/fluid/api_cn/layers_cn/image_resize_cn.rst

@@ -124,7 +124,7 @@ https://en.wikipedia.org/wiki/Trilinear_interpolation
     - **actual_shape** (Variable) - 可选输入，用于动态指定输出形状。如果指定actual_shape，图像将根据给定的形状调整大小，而不是根据指定形状的 :code:`out_shape` 和 :code:`scale` 进行调整。也就是说， :code:`actual_shape` 具有最高的优先级。如果希望动态指定输出形状，建议使用 :code:`out_shape` ，因为 :code:`actual_shape` 未来将被弃用。在使用actual_shape指定输出形状时，还需要设置out_shape和scale之一，否则在图形构建阶段会出现错误。默认值:None
     - **align_corners** （bool）- 一个可选的bool型参数，如果为True，则将输入和输出张量的4个角落像素的中心对齐，并保留角点像素的值。 默认值为True
     - **align_mode** （int）- 双线性插值的可选项。 可以是 '0' 代表src_idx = scale *（dst_indx + 0.5）-0.5；如果为'1' ，代表src_idx = scale * dst_index。
-    - **data_format** （str，可选）- 对于4-D Tensor，支持 NCHW(num_batches, channels, height, width) 或者 NHWC(num_batches, height, width, channels)，对于5-D Tensor，支持 NCDHW(num_batches, channels, depth, height, width)或者 NDHWC(num_batches, depth, height, width, channels)，默认值：'NCHW'。
+    - **data_format** （str，可选）- 指定输入的数据格式，输出的数据格式将与输入保持一致。对于4-D Tensor，支持 NCHW(num_batches, channels, height, width) 或者 NHWC(num_batches, height, width, channels)，对于5-D Tensor，支持 NCDHW(num_batches, channels, depth, height, width)或者 NDHWC(num_batches, depth, height, width, channels)，默认值：'NCHW'。
 
 返回：4-D Tensor，形状为 (num_batches, channels, out_h, out_w) 或 (num_batches, out_h, out_w, channels)；或者5-D Tensor，形状为 (num_batches, channels, out_d, out_h, out_w) 或 (num_batches, out_d, out_h, out_w, channels)。
 

doc/fluid/api_cn/layers_cn/lrn_cn.rst

@@ -28,7 +28,7 @@ lrn
     - **alpha** （float，可选）- 缩放参数，正数。默认值为1e-4。
     - **beta** （float，可选）- 指数，正数。默认值为0.75。
     - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
-    - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCHW"或"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
+    - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
 
 
 返回：局部响应正则化得到的输出特征，数据类型及维度和input相同。

doc/fluid/api_cn/layers_cn/resize_bilinear_cn.rst

@@ -59,7 +59,7 @@ align_corners和align_mode是可选参数，插值的计算方法可以由它们
     - **actual_shape** (Variable) - 可选输入，用于动态指定输出形状。如果指定actual_shape，图像将根据给定的形状调整大小，而不是根据指定形状的 :code:`out_shape` 和 :code:`scale` 进行调整。也就是说， :code:`actual_shape` 具有最高的优先级。如果希望动态指定输出形状，建议使用 :code:`out_shape` , 因为 :code:`out_shape` 未来将被弃用。在使用actual_shape指定输出形状时，还需要设置out_shape和scale之一，否则在图形构建阶段会出现错误。默认值为None。
     - **align_corners** （bool）- 一个可选的bool型参数，如果为True，则将输入和输出张量的4个角落像素的中心对齐，并保留角点像素的值。 默认值为True
     - **align_mode** （int）- 双线性插值的可选项。 可以是'0'代表src_idx = scale *（dst_indx + 0.5）-0.5；如果为'1' ，代表src_idx = scale * dst_index。
-    - **data_format** （str，可选）- 数据格式，支持 NCHW(num_batches, channels, height, width) 或者 NHWC(num_batches, height, width, channels)，默认值：'NCHW'。
+    - **data_format** （str，可选）- 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
 
 返回：4-D Tensor，形状为 (num_batches, channels, out_h, out_w) 或 (num_batches, out_h, out_w, channels)。
 

doc/fluid/api_cn/layers_cn/resize_nearest_cn.rst

@@ -55,7 +55,7 @@ resize_nearest
   - **name** (str|None) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。默认值为None。
   - **actual_shape** (Variable) - 可选输入，用于动态指定输出形状。如果指定actual_shape，图像将根据给定的形状调整大小，而不是根据指定形状的 :code:`out_shape` 和 :code:`scale` 进行调整。也就是说， :code:`actual_shape` 具有最高的优先级。如果希望动态指定输出形状，建议使用 :code:`out_shape` , 因为 :code:`out_shape` 未来将被弃用。在使用actual_shape指定输出形状时，还需要设置out_shape和scale之一，否则在图形构建阶段会出现错误。默认值为None。
   - **align_corners** （bool）- 一个可选的bool型参数，如果为True，则将输入和输出张量的4个角落像素的中心对齐，并保留角点像素的值。 默认值为True。
-  - **data_format** （str，可选）- 数据格式，支持 NCHW(num_batches, channels, height, width) 或者 NHWC(num_batches, height, width, channels)，默认值：'NCHW'。
+  - **data_format** （str，可选）- 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。
 
 返回：4-D Tensor，形状为 (num_batches, channels, out_h, out_w) 或 (num_batches, out_h, out_w, channels)。
 

doc/fluid/api_cn/layers_cn/resize_trilinear_cn.rst

@@ -54,7 +54,7 @@ Align_corners和align_mode都是可选参数，可以用来设置插值的计算
   - **actual_shape** (Variable) – 可选输入， 动态设置输出张量的形状。 如果提供该值， 图片放缩会依据此形状进行， 而非依据 ``out_shape`` 和 ``scale`` 。 即为， ``actual_shape`` 具有最高的优先级。 如果想动态指明输出形状，推荐使用 ``out_shape`` ，因为 ``actual_shape`` 未来将被弃用。 当使用 ``actual_shape`` 来指明输出形状， ``out_shape`` 和 ``scale`` 也应该进行设置, 否则在图形生成阶段将会报错。默认: None
   - **align_corners** （bool）- 一个可选的bool型参数，如果为True，则将输入和输出张量的4个角落像素的中心对齐，并保留角点像素的值。 默认值：True
   - **align_mode** (bool) - (int,默认为'1')，双线性插值选项，src_idx = scale*(dst_index+0.5)-0.5时取'0'，src_idx = scale*dst_index时取'1'。
-  - **data_format** （str，可选）- 支持 NCDHW(num_batches, channels, depth, height, width)或者 NDHWC(num_batches, depth, height, width, channels)，默认值：'NCDHW'。
+  - **data_format** （str，可选）- 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCDHW"。
 
 返回：5-D Tensor，形状为 (num_batches, channels, out_d, out_h, out_w) 或 (num_batches, out_d, out_h, out_w, channels)。