Cherrypick en doc: reorder_lod_tensor_by_rank , map_reader,...

Cherrypick  en doc: reorder_lod_tensor_by_rank , map_reader, WeightNormParamAttr, io.compose  (#20463)

* modify map_reader en doc (#20229)

* modify WeightNormParamAttr en doc (#20218)

* modify reorder_lod_tensor_by_rank en doc

* modify compose en doc (#20217)

paddle/fluid/API.spec

@@ -94,9 +94,9 @@ paddle.fluid.io.DataLoader.__init__
 paddle.fluid.io.DataLoader.from_dataset (ArgSpec(args=['dataset', 'places', 'drop_last'], varargs=None, keywords=None, defaults=(True,)), ('document', 'eb8b6d31e1c2ec2ca8ebbb62fcf46557'))
 paddle.fluid.io.DataLoader.from_generator (ArgSpec(args=['feed_list', 'capacity', 'use_double_buffer', 'iterable', 'return_list'], varargs=None, keywords=None, defaults=(None, None, True, True, False)), ('document', 'e3bdde36774236c3e381d2218e9cc09e'))
 paddle.fluid.io.cache (ArgSpec(args=['reader'], varargs=None, keywords=None, defaults=None), ('document', '1676886070eb607cb608f7ba47be0d3c'))
-paddle.fluid.io.map_readers (ArgSpec(args=['func'], varargs='readers', keywords=None, defaults=None), ('document', '77cbadb09df588e21e5cc0819b69c87d'))
+paddle.fluid.io.map_readers (ArgSpec(args=['func'], varargs='readers', keywords=None, defaults=None), ('document', '2d0903e1d2f00b4f1d6618e6b5310121'))
 paddle.fluid.io.buffered (ArgSpec(args=['reader', 'size'], varargs=None, keywords=None, defaults=None), ('document', '0d6186f109feceb99f60ec50a0a624cb'))
-paddle.fluid.io.compose (ArgSpec(args=[], varargs='readers', keywords='kwargs', defaults=None), ('document', '884291104e1c3f37f33aae44b7deeb0d'))
+paddle.fluid.io.compose (ArgSpec(args=[], varargs='readers', keywords='kwargs', defaults=None), ('document', '81c933c8da58041d91f084dcf6322349'))
 paddle.fluid.io.chain (ArgSpec(args=[], varargs='readers', keywords=None, defaults=None), ('document', 'e0311508658a7e741fc39feea8be0ad2'))
 paddle.fluid.io.shuffle (ArgSpec(args=['reader', 'buf_size'], varargs=None, keywords=None, defaults=None), ('document', 'e42ea6fee23ce26b23cb142cd1d6522d'))
 paddle.fluid.io.firstn (ArgSpec(args=['reader', 'n'], varargs=None, keywords=None, defaults=None), ('document', 'c5bb8f7dd4f917f1569a368aab5b8aad'))
@@ -379,7 +379,7 @@ paddle.fluid.layers.StaticRNN.step (ArgSpec(args=['self'], varargs=None, keyword
 paddle.fluid.layers.StaticRNN.step_input (ArgSpec(args=['self', 'x'], varargs=None, keywords=None, defaults=None), ('document', '903387ec11f3d0bf46821d31a68cffa5'))
 paddle.fluid.layers.StaticRNN.step_output (ArgSpec(args=['self', 'o'], varargs=None, keywords=None, defaults=None), ('document', '252890d4c3199a7623ab8667e13fd837'))
 paddle.fluid.layers.StaticRNN.update_memory (ArgSpec(args=['self', 'mem', 'var'], varargs=None, keywords=None, defaults=None), ('document', '7a0000520f179f35239956a5ba55119f'))
-paddle.fluid.layers.reorder_lod_tensor_by_rank (ArgSpec(args=['x', 'rank_table'], varargs=None, keywords=None, defaults=None), ('document', '5b552a1f0f7eb4dacb768a975ba15d08'))
+paddle.fluid.layers.reorder_lod_tensor_by_rank (ArgSpec(args=['x', 'rank_table'], varargs=None, keywords=None, defaults=None), ('document', 'db67cfcdd20ff6380d125a7553d62121'))
 paddle.fluid.layers.Print (ArgSpec(args=['input', 'first_n', 'message', 'summarize', 'print_tensor_name', 'print_tensor_type', 'print_tensor_shape', 'print_tensor_lod', 'print_phase'], varargs=None, keywords=None, defaults=(-1, None, 20, True, True, True, True, 'both')), ('document', '3130bed32922b9fd84ce2dea6250f635'))
 paddle.fluid.layers.is_empty (ArgSpec(args=['x', 'cond'], varargs=None, keywords=None, defaults=(None,)), ('document', '3011dc695f490afdf504dc24f628319a'))
 paddle.fluid.layers.sigmoid (ArgSpec(args=['x', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '7bd26680989f33301a4a68000d5af4b0'))
@@ -1098,7 +1098,7 @@ paddle.fluid.CUDAPinnedPlace ('paddle.fluid.core_avx.CUDAPinnedPlace', ('documen
 paddle.fluid.CUDAPinnedPlace.__init__ __init__(self: paddle.fluid.core_avx.CUDAPinnedPlace) -> None
 paddle.fluid.ParamAttr ('paddle.fluid.param_attr.ParamAttr', ('document', '7b5bfe856689036b8fffb71af1558e5c'))
 paddle.fluid.ParamAttr.__init__ (ArgSpec(args=['self', 'name', 'initializer', 'learning_rate', 'regularizer', 'trainable', 'gradient_clip', 'do_model_average'], varargs=None, keywords=None, defaults=(None, None, 1.0, None, True, None, True)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
-paddle.fluid.WeightNormParamAttr ('paddle.fluid.param_attr.WeightNormParamAttr', ('document', 'b5ae1698ea72d5a9428000b916a67379'))
+paddle.fluid.WeightNormParamAttr ('paddle.fluid.param_attr.WeightNormParamAttr', ('document', 'ea029ec9e0dea75f136211c433154f25'))
 paddle.fluid.WeightNormParamAttr.__init__ (ArgSpec(args=['self', 'dim', 'name', 'initializer', 'learning_rate', 'regularizer', 'trainable', 'gradient_clip', 'do_model_average'], varargs=None, keywords=None, defaults=(None, None, None, 1.0, None, True, None, False)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
 paddle.fluid.DataFeeder ('paddle.fluid.data_feeder.DataFeeder', ('document', 'd9e64be617bd5f49dbb08ac2bc8665e6'))
 paddle.fluid.DataFeeder.__init__ (ArgSpec(args=['self', 'feed_list', 'place', 'program'], varargs=None, keywords=None, defaults=(None,)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))

paddle/fluid/operators/reorder_lod_tensor_by_rank_op.cc

@@ -30,7 +30,7 @@ class ReorderLoDTensorByRankTableOpProtoMaker
     AddInput("RankTable",
              "(LoDRankTable), the rank table according to which Input(X) is "
              "reordered.");
-    AddOutput("Out", "(LoDTensor), the reordered lod tensor.");
+    AddOutput("Out", "LoDTensor, the reordered lod tensor.");
     AddComment(R"DOC(ReorderLoDTensorByRankTable operator.
 
 Input(X) is a batch of sequences. Input(RankTable) stores new orders of the
@@ -57,7 +57,8 @@ X = [Slice0, Slice1, Slice2, Slice3] and its LoD information is empty. The
 indices in RankTable are [3, 0, 2, 1].
 Out = [Slice3, Slice0, Slice2, Slice1] with no LoD information is appended.
 
-NOTE: This operator sorts Input(X) according to a given LoDRankTable which does
+**NOTE**: 
+This operator sorts Input(X) according to a given LoDRankTable which does
 not need to be calculated according to Input(X). It can be calculated according
 to another different sequence, and then this operator sorts Input(X) according
 to the given LoDRankTable.

python/paddle/fluid/layers/control_flow.py

@@ -2215,12 +2215,11 @@ def reorder_lod_tensor_by_rank(x, rank_table):
     ${comment}
 
     Args:
-    
-        x(${x_type}): ${x_comment}
-        rank_table(${rank_table_type}): ${rank_table_type}
+        x(${x_type}): ${x_comment}.
+        rank_table(${rank_table_type}): ${rank_table_comment}.
     
     Returns:
-        out(${out_type}): ${out_comment} 
+        out(${out_type}): ${out_comment}.
 
     Examples:
         .. code-block:: python

python/paddle/fluid/param_attr.py

@@ -183,7 +183,7 @@ class ParamAttr(object):
 
 class WeightNormParamAttr(ParamAttr):
     """
-    Used for weight Norm. Weight Norm is a reparameterization of the weight vectors
+    Parameter of weight Norm. Weight Norm is a reparameterization of the weight vectors
     in a neural network that decouples the magnitude of those weight vectors from
     their direction. Weight Norm has been implemented as discussed in this
     paper: `Weight Normalization: A Simple Reparameterization to Accelerate
@@ -191,17 +191,27 @@ class WeightNormParamAttr(ParamAttr):
     <https://arxiv.org/pdf/1602.07868.pdf>`_.
 
     Args:
-        dim(int): Dimension over which to compute the norm. Default None.
-        name(str): The parameter's name. Default None.
-        initializer(Initializer): The method to initial this parameter. Default None.
-        learning_rate(float): The parameter's learning rate. The learning rate when
-            optimize is :math:`global\_lr * parameter\_lr * scheduler\_factor`.
+        dim(int): Dimension over which to compute the norm. Dim is a non-negative
+            number which is less than the rank of weight Tensor. For Example, dim can
+            be choosed from 0, 1, 2, 3 for convolution whose weight shape is [cout, cin, kh, kw]
+            and rank is 4. Default None, meaning that all elements will be normalized.
+        name(str, optional): The parameter's name. Default None, meaning that the name would
+            be created automatically. Please refer to :ref:`api_guide_Name` for more details.
+        initializer(Initializer): The method to initialize this parameter, such as
+            ``initializer = fluid.initializer.ConstantInitializer(1.0)``. Default None,
+            meaning that the weight parameter is initialized by Xavier initializer, and
+            the bias parameter is initialized by 0.
+        learning_rate(float32): The parameter's learning rate when
+            optimizer is :math:`global\_lr * parameter\_lr * scheduler\_factor`.
             Default 1.0.
-        regularizer(WeightDecayRegularizer): Regularization factor. Default None.
-        trainable(bool): Whether this parameter is trainable. Default True.
-        gradient_clip(BaseGradientClipAttr): The method to clip this parameter's
-            gradient. Default None.
-        do_model_average(bool): Whether this parameter should do model average.
+        regularizer(WeightDecayRegularizer): Regularization factor, such as
+            ``regularizer = fluid.regularizer.L2DecayRegularizer(regularization_coeff=0.1)``.
+            Default None, meaning that there is no regularization.
+        trainable(bool, optional): Whether this parameter is trainable. Default True.
+        gradient_clip: The method to clip this parameter's gradient, such as
+            ``gradient_clip = fluid.clip.GradientClipByNorm(clip_norm=2.0))`` .
+            Default None, meaning that there is no gradient clip.
+        do_model_average(bool, optional): Whether this parameter should do model average.
             Default False.
 
     Examples:
@@ -212,8 +222,14 @@ class WeightNormParamAttr(ParamAttr):
             fc = fluid.layers.fc(input=data,
                                  size=1000,
                                  param_attr=fluid.WeightNormParamAttr(
-                                      dim=None,
-                                      name='weight_norm_param'))
+                                          dim=None,
+                                          name='weight_norm_param',
+                                          initializer=fluid.initializer.ConstantInitializer(1.0),
+                                          learning_rate=1.0,
+                                          regularizer=fluid.regularizer.L2DecayRegularizer(regularization_coeff=0.1),
+                                          trainable=True,
+                                          gradient_clip=fluid.clip.GradientClipByNorm(clip_norm=2.0),
+                                          do_model_average=False))
 
     """
     # List to record the parameters reparameterized by weight normalization.

python/paddle/reader/decorator.py

@@ -60,13 +60,33 @@ def cache(reader):
 def map_readers(func, *readers):
     """
     Creates a data reader that outputs return value of function using
-    output of each data readers as arguments.
+    output of each data reader as arguments.
 
-    :param func: function to use. The type of func should be (Sample) => Sample
-    :type: callable
-    :param readers: readers whose outputs will be used as arguments of func.
-    :return: the created data reader.
-    :rtype: callable
+    If input readers output the following data entries: 2 3,
+    and the input func is mul(x, y),
+    the output of the resulted reader will be 6.
+
+
+    Args:
+        func: a function to read data and compute result, the output of this function 
+              will be set as the output of the resulted data reader.
+        readers (Reader|list of Reader): list of readers whose outputs will be used as arguments of func.
+ 
+    Returns:
+        the resulted data reader (Reader)
+
+    Examples:
+
+        .. code-block:: python
+
+         import paddle.reader
+         d = {"h": 0, "i": 1}
+         def func(x):
+             return d[x]
+         def reader():
+             yield "h"
+             yield "i"
+         map_reader_result = paddle.reader.map_readers(func, reader)
     """
 
     def reader():
@@ -187,16 +207,29 @@ def compose(*readers, **kwargs):
     The composed reader will output:
     (1, 2, 3, 4, 5)
 
-    :param readers: readers that will be composed together.
-    :param check_alignment: if True, will check if input readers are aligned
-        correctly. If False, will not check alignment and trailing outputs
-        will be discarded. Defaults to True.
-    :type check_alignment: bool
-
-    :return: the new data reader.
-
-    :raises ComposeNotAligned: outputs of readers are not aligned.
-        Will not raise when check_alignment is set to False.
+    Args:
+        readers (Reader|list of Reader): readers that will be composed together. 
+        check_alignment(bool, optional): Indicates whether the input readers are checked for
+                              alignment. If True, whether input readers are aligned
+                              correctly will be checked, else alignment will not be checkout and trailing outputs
+                              will be discarded. Defaults to True.
+
+    Returns: 
+        the new data reader (Reader).
+
+    Raises:
+        ComposeNotAligned: outputs of readers are not aligned. This will not raise if check_alignment is set to False.
+  
+    Examples:
+        .. code-block:: python
+
+          import paddle.fluid as fluid
+          def reader_creator_10(dur):
+              def reader():
+                 for i in range(10):
+                     yield i
+              return reader
+          reader = fluid.io.compose(reader_creator_10(0), reader_creator_10(0))
     """
     check_alignment = kwargs.pop('check_alignment', True)