[Docs][en] adjust code example format (#44679)

* add name attribute to code-block, test=document_fix

* remove redundant labels, test=document_fix

* remove redundant labels (from upstream), test=document_fix

* more COPY-FROM (try multiple code example), test=document_fix

* empty commit, try to trigger PR-CI-build

* fix some `Examples:` format issues

* fix some ci errors

python/paddle/distribution/transform.py

@@ -590,7 +590,7 @@ class ChainTransform(Transform):
 class ExpTransform(Transform):
     r"""Exponent transformation with mapping :math:`y = \exp(x)`.
 
-    Exapmles:
+    Examples:
 
         .. code-block:: python
 
@@ -1169,7 +1169,7 @@ class StickBreakingTransform(Transform):
 class TanhTransform(Transform):
     r"""Tanh transformation with mapping :math:`y = \tanh(x)`.
 
-    Examples
+    Examples:
 
         .. code-block:: python
 

python/paddle/fluid/dataloader/dataset.py

@@ -413,7 +413,7 @@ class Subset(Dataset):
     Returns:
         Dataset: A Dataset which is the subset of the original dataset.
     
-    Example code:
+    Examples:
 
         .. code-block:: python
 
@@ -455,7 +455,7 @@ def random_split(dataset, lengths, generator=None):
     Returns:
         Datasets: A list of subset Datasets, which are the non-overlapping subsets of the original Dataset.
 
-    Example code:
+    Examples:
 
         .. code-block:: python
 

python/paddle/fluid/dygraph/base.py

@@ -485,8 +485,9 @@ def grad(outputs,
         inside `inputs`, and the i-th returned Tensor is the sum of gradients of 
         `outputs` with respect to the i-th `inputs`.
 
-    Examples 1:
+    Examples:
         .. code-block:: python
+            :name: code-example-1
 
             import paddle
 
@@ -519,8 +520,8 @@ def grad(outputs,
             print(test_dygraph_grad(create_graph=False)) # [2.]
             print(test_dygraph_grad(create_graph=True)) # [4.]
 
-    Examples 2:
         .. code-block:: python
+            :name: code-example-2
 
             import paddle
 

python/paddle/fluid/dygraph/layers.py

@@ -98,6 +98,26 @@ class Layer(object):
 
     Returns:
         None
+
+    Examples:
+        .. code-block:: python
+
+            import paddle
+            class MyLayer(paddle.nn.Layer):
+                def __init__(self):
+                    super(MyLayer, self).__init__()
+                    self._linear = paddle.nn.Linear(1, 1)
+                    self._dropout = paddle.nn.Dropout(p=0.5)
+                def forward(self, input):
+                    temp = self._linear(input)
+                    temp = self._dropout(temp)
+                    return temp
+            x = paddle.randn([10, 1], 'float32')
+            mylayer = MyLayer()
+            mylayer.eval()  # set mylayer._dropout to eval mode
+            out = mylayer(x)
+            mylayer.train()  # set mylayer._dropout to train mode
+            out = mylayer(x)
     """
 
     def __init__(self, name_scope=None, dtype="float32"):

python/paddle/fluid/executor.py

@@ -1187,8 +1187,9 @@ class Executor(object):
                results are spliced together in dimension 0 for the same Tensor values
                (Tensors in fetch_list) on different devices.
 
-        Examples 1:
+        Examples:
             .. code-block:: python
+                :name: code-example-1
 
                 import paddle
                 import numpy
@@ -1215,9 +1216,10 @@ class Executor(object):
                 print(array_val)
                 # [array([0.02153828], dtype=float32)]
 
-        Examples 2:
             .. code-block:: python
+                :name: code-example-2
 
+                # required: gpu
                 import paddle
                 import numpy as np
 

python/paddle/fluid/initializer.py

@@ -1187,7 +1187,7 @@ def calculate_gain(nonlinearity, param=None):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
+
             import paddle
             gain = paddle.nn.initializer.calculate_gain('tanh') # 5.0 / 3
             gain = paddle.nn.initializer.calculate_gain('leaky_relu', param=1.0) # 1.0 = math.sqrt(2.0 / (1+param^2))

python/paddle/incubate/autotune.py

@@ -54,7 +54,6 @@ def set_config(config=None):
 
     Examples:
         .. code-block:: python
-            :name: auto-tuning
 
             import paddle
             import json

python/paddle/nn/functional/activation.py

@@ -601,7 +601,6 @@ def rrelu(x, lower=1. / 8., upper=1. / 3., training=True, name=None):
 
     Examples:
         .. code-block:: python
-            :name: rrelu-example
 
             import paddle
             import paddle.nn.functional as F

python/paddle/nn/functional/loss.py

@@ -2209,10 +2209,11 @@ def cross_entropy(input,
         2. if soft_label = True, the dimension of return value is :math:`[N_1, N_2, ..., N_k, 1]` . 
 
 
-     Example1(hard labels):
+    Examples:
 
         .. code-block:: python
 
+            # hard labels
             import paddle
             paddle.seed(99999)
             N=100
@@ -2229,11 +2230,9 @@ def cross_entropy(input,
                                        label)
             print(dy_ret.numpy()) #[5.41993642]
 
-
-    Example2(soft labels):
-
         .. code-block:: python
 
+            # soft labels
             import paddle
             paddle.seed(99999)
             axis = -1
@@ -2900,7 +2899,6 @@ def cosine_embedding_loss(input1,
 
     Examples:
         .. code-block:: python
-          :name: code-example1
 
             import paddle
 

python/paddle/nn/functional/pooling.py

@@ -1296,7 +1296,6 @@ def adaptive_avg_pool1d(x, output_size, name=None):
         Tensor: The result of 1D adaptive average pooling. Its data type is same as input.
     Examples:
         .. code-block:: python
-          :name: adaptive_avg_pool1d-example
 
             # average adaptive pool1d
             # suppose input data in shape of [N, C, L], `output_size` is m or [m],

python/paddle/nn/functional/vision.py

@@ -367,7 +367,6 @@ def pixel_unshuffle(x, downscale_factor, data_format="NCHW", name=None):
 
     Examples:
         .. code-block:: python
-            :name: pixel_unshuffle-example
 
             import paddle
             import paddle.nn.functional as F
@@ -424,7 +423,6 @@ def channel_shuffle(x, groups, data_format="NCHW", name=None):
 
     Examples:
         .. code-block:: python
-            :name: channel_shuffle-example
 
             import paddle
             import paddle.nn.functional as F

python/paddle/nn/initializer/constant.py

@@ -26,7 +26,7 @@ class Constant(ConstantInitializer):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
+
             import paddle
             import paddle.nn as nn
 

python/paddle/nn/initializer/normal.py

@@ -72,7 +72,6 @@ class TruncatedNormal(TruncatedNormalInitializer):
 
     Examples:
         .. code-block:: python
-            :name: initializer_TruncatedNormal-example
 
             import paddle
 

python/paddle/nn/initializer/uniform.py

@@ -30,7 +30,6 @@ class Uniform(UniformInitializer):
 
     Examples:
         .. code-block:: python
-            :name: initializer_Uniform-example
 
             import paddle
 

python/paddle/nn/initializer/xavier.py

@@ -41,7 +41,6 @@ class XavierNormal(XavierInitializer):
 
     Examples:
         .. code-block:: python
-            :name: initializer_XavierNormal-example
 
             import paddle
 
@@ -97,7 +96,6 @@ class XavierUniform(XavierInitializer):
 
     Examples:
         .. code-block:: python
-            :name: initializer_XavierUniform-example
 
             import paddle
 

python/paddle/nn/layer/activation.py

@@ -486,7 +486,6 @@ class RReLU(Layer):
 
     Examples:
         .. code-block:: python
-            :name: RReLU-example
 
             import paddle
 

python/paddle/nn/layer/loss.py

@@ -328,10 +328,11 @@ class CrossEntropyLoss(Layer):
 
             2. if soft_label = True, the dimension of return value is :math:`[N_1, N_2, ..., N_k, 1]` . 
 
-     Example1(hard labels):
+    Examples:
 
         .. code-block:: python
             
+            # hard labels
             import paddle
             paddle.seed(99999)
             N=100
@@ -348,11 +349,9 @@ class CrossEntropyLoss(Layer):
                                        label)
             print(dy_ret.numpy()) #[5.41993642]
 
-
-    Example2(soft labels):
-
         .. code-block:: python
 
+            # soft labels
             import paddle
             paddle.seed(99999)
             axis = -1
@@ -1435,7 +1434,6 @@ class CosineEmbeddingLoss(Layer):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
 
             import paddle
 

python/paddle/nn/layer/pooling.py

@@ -644,7 +644,7 @@ class AdaptiveAvgPool1D(Layer):
 
     Examples:
         .. code-block:: python
-            :name: AdaptiveAvgPool1D-example
+
             # average adaptive pool1d
             # suppose input data in shape of [N, C, L], `output_size` is m or [m],
             # output shape is [N, C, m], adaptive pool divide L dimension

python/paddle/nn/layer/vision.py

@@ -110,7 +110,6 @@ class PixelUnshuffle(Layer):
 
     Examples:
         .. code-block:: python
-            :name: PixelUnshuffle-example
 
             import paddle
             import paddle.nn as nn
@@ -173,7 +172,6 @@ class ChannelShuffle(Layer):
 
     Examples:
         .. code-block:: python
-            :name: ChannelShuffle-example
 
             import paddle
             import paddle.nn as nn

python/paddle/profiler/profiler.py

@@ -173,7 +173,6 @@ def export_chrome_tracing(dir_name: str,
         The return value can be used as parameter ``on_trace_ready`` in :ref:`Profiler <api_paddle_profiler_Profiler>` .
 
         .. code-block:: python
-            :name: code-example1
 
             # required: gpu
             import paddle.profiler as profiler
@@ -224,7 +223,6 @@ def export_protobuf(dir_name: str,
         The return value can be used as parameter ``on_trace_ready`` in :ref:`Profiler <api_paddle_profiler_Profiler>` .
 
         .. code-block:: python
-            :name: code-example1
 
             # required: gpu
             import paddle.profiler as profiler

python/paddle/profiler/utils.py

@@ -138,7 +138,6 @@ def load_profiler_result(filename: str):
 
     Examples:
         .. code-block:: python
-            :name: code-example1
 
             # required: gpu
             import paddle.profiler as profiler

python/paddle/static/io.py

@@ -423,6 +423,25 @@ def save_to_file(path, content):
         content(bytes): Content to write.
     Returns:
         None
+
+    Examples:
+        .. code-block:: python
+
+            import paddle
+            paddle.enable_static()
+            path_prefix = "./infer_model"
+            # 用户自定义网络，此处用 softmax 回归为例。
+            image = paddle.static.data(name='img', shape=[None, 28, 28], dtype='float32')
+            label = paddle.static.data(name='label', shape=[None, 1], dtype='int64')
+            predict = paddle.static.nn.fc(image, 10, activation='softmax')
+            loss = paddle.nn.functional.cross_entropy(predict, label)
+            exe = paddle.static.Executor(paddle.CPUPlace())
+            exe.run(paddle.static.default_startup_program())
+            # 序列化参数
+            serialized_params = paddle.static.serialize_persistables([image], [predict], exe)
+            # 将序列化之后的参数保存到文件
+            params_path = path_prefix + ".params"
+            paddle.static.save_to_file(params_path, serialized_params)
     """
 
     if not isinstance(content, bytes):
@@ -675,6 +694,28 @@ def load_from_file(path):
         path(str): Path of an existed file.
     Returns:
         bytes: Content of file.
+
+    Examples:
+
+        .. code-block:: python
+
+            import paddle
+            paddle.enable_static()
+            path_prefix = "./infer_model"
+            # 用户自定义网络，此处用 softmax 回归为例。
+            image = paddle.static.data(name='img', shape=[None, 28, 28], dtype='float32')
+            label = paddle.static.data(name='label', shape=[None, 1], dtype='int64')
+            predict = paddle.static.nn.fc(image, 10, activation='softmax')
+            loss = paddle.nn.functional.cross_entropy(predict, label)
+            exe = paddle.static.Executor(paddle.CPUPlace())
+            exe.run(paddle.static.default_startup_program())
+            # 序列化参数
+            serialized_params = paddle.static.serialize_persistables([image], [predict], exe)
+            # 将序列化之后的参数保存到文件
+            params_path = path_prefix + ".params"
+            paddle.static.save_to_file(params_path, serialized_params)
+            # 从文件加载序列化之后的参数
+            serialized_params_copy = paddle.static.load_from_file(params_path)
     """
     with open(path, 'rb') as f:
         data = f.read()

python/paddle/tensor/creation.py

@@ -178,7 +178,6 @@ def logspace(start, stop, num, base=10.0, dtype=None, name=None):
 
     Examples:
         .. code-block:: python
-            :name: logspace-example
 
             import paddle
             data = paddle.logspace(0, 10, 5, 2, 'float32')
@@ -492,7 +491,6 @@ def ones(shape, dtype=None, name=None):
 
     Examples:
         .. code-block:: python
-          :name: ones-example
 
             import paddle 
 
@@ -713,7 +711,6 @@ def full(shape, fill_value, dtype=None, name=None):
 
     Examples:
         .. code-block:: python
-           :name: code-example1
 
             import paddle
 
@@ -1110,6 +1107,7 @@ def diagflat(x, offset=0, name=None):
 
     Examples:
         .. code-block:: python
+            :name: code-example-1
 
             import paddle
 
@@ -1135,6 +1133,7 @@ def diagflat(x, offset=0, name=None):
             #  [0 0 3 0]]
 
         .. code-block:: python
+            :name: code-example-2
 
             import paddle
 
@@ -1240,6 +1239,7 @@ def diag(x, offset=0, padding_value=0, name=None):
 
     Examples:
         .. code-block:: python
+            :name: code-example-1
 
             import paddle
 
@@ -1265,6 +1265,7 @@ def diag(x, offset=0, padding_value=0, name=None):
             #  [6 6 3]]
 
         .. code-block:: python
+            :name: code-example-2
 
             import paddle
 
@@ -1485,7 +1486,6 @@ def assign(x, output=None):
  
     Examples:
         .. code-block:: python
-          :name: assign-example
 
             import paddle
             import numpy as np
@@ -1777,7 +1777,6 @@ def tril_indices(row, col, offset=0, dtype='int64'):
 
     Examples:
         .. code-block:: python
-            :name: tril_indices-example
 
             import paddle
             

python/paddle/tensor/linalg.py

@@ -3267,7 +3267,6 @@ def corrcoef(x, rowvar=True, name=None):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
 
             import paddle
 

python/paddle/tensor/manipulation.py

@@ -619,7 +619,6 @@ def crop(x, shape=None, offsets=None, name=None):
     Examples:
 
         .. code-block:: python
-          :name: code-example1
 
             import paddle
             x = paddle.to_tensor([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
@@ -1975,7 +1974,7 @@ def squeeze(x, axis=None, name=None):
 
     Examples:
         .. code-block:: python
-	  :name: code-example1
+
             import paddle
             
             x = paddle.rand([5, 1, 10])
@@ -2187,7 +2186,7 @@ def unique(x,
 
     Examples:
         .. code-block:: python
-	  :name: code-example1
+
             import paddle
 
             x = paddle.to_tensor([2, 3, 3, 1, 5, 3])
@@ -3219,7 +3218,6 @@ def reshape(x, shape, name=None):
 
     Examples:
         .. code-block:: python
-           :name: code-example1
 
             import paddle
 
@@ -4185,7 +4183,6 @@ def take_along_axis(arr, indices, axis):
     
     Examples:
         .. code-block:: python
-           :name: code-example1
 
             import paddle
 
@@ -4251,7 +4248,6 @@ def put_along_axis(arr, indices, values, axis, reduce='assign'):
     
     Examples:
         .. code-block:: python
-            :name: code-example1
 
             import paddle
 

python/paddle/tensor/math.py

@@ -288,7 +288,6 @@ def multiplex(inputs, index, name=None):
     Examples:
 
         .. code-block:: python
-            :name: code-example1
 
             import paddle
             
@@ -1376,7 +1375,6 @@ def count_nonzero(x, axis=None, keepdim=False, name=None):
     Examples:
 
         .. code-block:: python
-            :name: count_nonzero-example
 
             import paddle
             # x is a 2-D Tensor:
@@ -1468,7 +1466,7 @@ def add_n(inputs, name=None):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
+
             import paddle
 
             input0 = paddle.to_tensor([[1, 2, 3], [4, 5, 6]], dtype='float32')
@@ -4629,7 +4627,6 @@ def heaviside(x, y, name=None):
 
     Examples:
         .. code-block:: python
-            :name: heaviside-example
 
             import paddle
             x = paddle.to_tensor([-0.5, 0, 0.5])
@@ -4662,7 +4659,7 @@ def frac(x, name=None):
         Tensor: The output Tensor of frac.
 
     Examples:
-        .. code-block:: Python
+        .. code-block:: python
 
             import paddle
             import numpy as np

python/paddle/tensor/random.py

@@ -47,7 +47,6 @@ def bernoulli(x, name=None):
 
     Examples:
         .. code-block:: python
-            :name: bernoulli-example
 
             import paddle
 

python/paddle/tensor/search.py

@@ -225,7 +225,7 @@ def argmin(x, axis=None, keepdim=False, dtype="int64", name=None):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
+
             import paddle
 
             x =  paddle.to_tensor([[5,8,9,5],
@@ -447,7 +447,6 @@ def sort(x, axis=-1, descending=False, name=None):
     Examples:
 
         .. code-block:: python
-           :name: code-example1
 
             import paddle
 
@@ -849,7 +848,7 @@ def topk(x, k, axis=None, largest=True, sorted=True, name=None):
     Examples:
 
         .. code-block:: python
-          :name: code-example1
+
             import paddle
 
             data_1 = paddle.to_tensor([1, 4, 5, 7])

python/paddle/tensor/stat.py

@@ -272,7 +272,6 @@ def nanmedian(x, axis=None, keepdim=True, name=None):
 
     Examples:
         .. code-block:: python
-            :name: nanmedian-example
 
             import paddle
             x = paddle.to_tensor([[float('nan'), 2. , 3. ], [0. , 1. , 2. ]])

python/paddle/vision/ops.py

@@ -1075,7 +1075,6 @@ def psroi_pool(x, boxes, boxes_num, output_size, spatial_scale=1.0, name=None):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
 
             import paddle
             x = paddle.uniform([2, 490, 28, 28], dtype='float32')
@@ -1144,7 +1143,7 @@ class PSRoIPool(Layer):
 
     Examples:
         .. code-block:: python
-          :name: code-example1
+
             import paddle
             
             psroi_module = paddle.vision.ops.PSRoIPool(7, 1.0)
@@ -1350,7 +1349,7 @@ def roi_align(x,
 
     Examples:
         .. code-block:: python
-          :name: code-example1
+
             import paddle
             from paddle.vision.ops import roi_align
 
@@ -1426,7 +1425,7 @@ class RoIAlign(Layer):
 
     Examples:
         ..  code-block:: python
-          :name: code-example1
+
             import paddle
             from paddle.vision.ops import RoIAlign