fix paddle.Model en docs (#43537)

* add copy-from label for code examples, test=document_fix

* refine docs, test=document_fix

* add some output for code example, test=document_fix

* add `optional`, test=document_fix

* add missing parameters, test=document_fix

* add missing links for `ProgBarLogger` and `ModelCheckpoint`, test=document_fix

* update eval_batch example, test=document_fix

* fix typos in stack_outputs, test=document_fix

* np.random -> paddle.random, test=document_fix

python/paddle/hapi/model.py

@@ -934,20 +934,21 @@ class Model(object):
     Args:
         network (paddle.nn.Layer): The network is an instance of
             paddle.nn.Layer.
-        inputs (InputSpec|list|tuple|dict|None): `inputs`, entry points of network,
+        inputs (InputSpec|list|tuple|dict|None, optional): `inputs`, entry points of network,
             could be a InputSpec instance, or list/tuple of InputSpec instances,
             or dict ({name: InputSpec}), and it couldn't be None in static
-            graph.
-        labels (InputSpec|list|tuple|None): `labels`, entry points of network,
+            graph. Default: None.
+        labels (InputSpec|list|tuple|None, optional): `labels`, entry points of network,
             could be a InputSpec instnace or list/tuple of InputSpec instances,
             or None. For static graph, if labels is required in loss,
-            labels must be set. Otherwise, it could be None.
+            labels must be set. Otherwise, it could be None. Default: None.
 
 
     Examples:
         1. A common example
 
         .. code-block:: python
+          :name: code-example1
 
             import paddle
             import paddle.nn as nn
@@ -985,6 +986,7 @@ class Model(object):
         2. An example using mixed precision training.
 
         .. code-block:: python
+          :name: code-example2
 
             # required: gpu
             import paddle
@@ -1059,12 +1061,12 @@ class Model(object):
             inputs (numpy.ndarray|Tensor|list): Batch of input data. It could 
                 be a numpy array or paddle.Tensor, or a list of arrays or 
                 tensors (in case the model has multiple inputs).
-            labels (numpy.ndarray|Tensor|list): Batch of labels. It could be 
+            labels (numpy.ndarray|Tensor|list, optional): Batch of labels. It could be 
                 a numpy array or paddle.Tensor, or a list of arrays or tensors 
                 (in case the model has multiple labels). If has no labels, 
-                set None. Default is None.
-            update (bool): Whether update parameters after loss.backward() computing.
-                Using it to accumulate gradients. Default is True.
+                set None. Default: None.
+            update (bool, optional): Whether update parameters after loss.backward() computing.
+                Set it to False to accumulate gradients. Default: True.
 
         Returns:
             A list of scalar training loss if the model has no metrics,
@@ -1074,8 +1076,8 @@ class Model(object):
         Examples:
 
             .. code-block:: python
+              :name: code-example-train-batch
             
-              import numpy as np
                 import paddle
                 import paddle.nn as nn
                 from paddle.static import InputSpec
@@ -1093,10 +1095,11 @@ class Model(object):
                 optim = paddle.optimizer.SGD(learning_rate=1e-3,
                     parameters=model.parameters())
                 model.prepare(optim, paddle.nn.CrossEntropyLoss())
-              data = np.random.random(size=(4,784)).astype(np.float32)
-              label = np.random.randint(0, 10, size=(4, 1)).astype(np.int64)
+                data = paddle.rand((4, 784), dtype="float32")
+                label = paddle.randint(0, 10, (4, 1), dtype="int64")
                 loss = model.train_batch([data], [label])
                 print(loss)
+                # [array([2.192784], dtype=float32)]
         """
         loss = self._adapter.train_batch(inputs, labels, update)
         if fluid._non_static_mode() and self._input_info is None:
@@ -1112,10 +1115,10 @@ class Model(object):
             inputs (numpy.ndarray|Tensor|list): Batch of input data. It could 
                 be a numpy array or paddle.Tensor, or a list of arrays or 
                 tensors (in case the model has multiple inputs).
-            labels (numpy.ndarray|Tensor|list): Batch of labels. It could be 
+            labels (numpy.ndarray|Tensor|list, optional): Batch of labels. It could be 
                 a numpy array or paddle.Tensor, or a list of arrays or tensors 
                 (in case the model has multiple labels). If has no labels, 
-                set None. Default is None.
+                set None. Default: None.
 
         Returns:
             A list of scalar testing loss if the model has no metrics,
@@ -1125,8 +1128,8 @@ class Model(object):
         Examples:
 
             .. code-block:: python
+              :name: code-example-eval-batch
 
-              import numpy as np
                 import paddle
                 import paddle.nn as nn
                 from paddle.static import InputSpec
@@ -1144,11 +1147,12 @@ class Model(object):
                 optim = paddle.optimizer.SGD(learning_rate=1e-3,
                     parameters=model.parameters())
                 model.prepare(optim,
-                            paddle.nn.CrossEntropyLoss())
-              data = np.random.random(size=(4,784)).astype(np.float32)
-              label = np.random.randint(0, 10, size=(4, 1)).astype(np.int64)
-              loss = model.eval_batch([data], [label])
-              print(loss)
+                            paddle.nn.CrossEntropyLoss(), metrics=paddle.metric.Accuracy())
+                data = paddle.rand((4, 784), dtype="float32")
+                label = paddle.randint(0, 10, (4, 1), dtype="int64")
+                loss, acc = model.eval_batch([data], [label])
+                print(loss, acc)
+                # [array([2.8825705], dtype=float32)] [0.0]
         """
         loss = self._adapter.eval_batch(inputs, labels)
         if fluid._non_static_mode() and self._input_info is None:
@@ -1172,8 +1176,8 @@ class Model(object):
         Examples:
 
             .. code-block:: python
+              :name: code-example-predict-batch
 
-              import numpy as np
                 import paddle
                 import paddle.nn as nn
                 from paddle.static import InputSpec
@@ -1191,9 +1195,12 @@ class Model(object):
 
                 model = paddle.Model(net, input, label)
                 model.prepare()
-              data = np.random.random(size=(4,784)).astype(np.float32)
+                data = paddle.rand((1, 784), dtype="float32")
                 out = model.predict_batch([data])
                 print(out)
+                # [array([[0.08189095, 0.16740078, 0.06889386, 0.05085445, 0.10729759,
+                #          0.02217775, 0.14518553, 0.1591538 , 0.01808308, 0.17906217]],
+                #          dtype=float32)]
         """
         loss = self._adapter.predict_batch(inputs)
         if fluid._non_static_mode() and self._input_info is None:
@@ -1229,6 +1236,7 @@ class Model(object):
         Examples:
 
             .. code-block:: python
+              :name: code-example-save
 
                 import paddle
                 import paddle.nn as nn
@@ -1294,14 +1302,14 @@ class Model(object):
                 optimizer states. The files would be `path.pdparams` and
                 `path.pdopt` separately, and the latter is not necessary
                 when no need to restore.
-            skip_mismatch (bool): Whether to skip the loading of mismatch
+            skip_mismatch (bool, optional): Whether to skip the loading of mismatch
                 parameter or raise an error when mismatch happens (not found
                 the parameter in file storing model states of or receives a
-                mismatch shape).
-            reset_optimizer (bool): If True, ignore the providing file storing
+                mismatch shape). Default: False.
+            reset_optimizer (bool, optional): If True, ignore the providing file storing
                 optimizer states and initialize optimizer states from scratch.
                 Otherwise, restore optimizer states from `path.pdopt` if
-                a optimizer has been set to the model. Default False.
+                a optimizer has been set to the model. Default: False.
 
         Returns:
             None
@@ -1309,6 +1317,7 @@ class Model(object):
         Examples:
 
             .. code-block:: python
+              :name: code-example-load
 
                 import paddle
                 import paddle.nn as nn
@@ -1395,6 +1404,7 @@ class Model(object):
         Examples:
 
             .. code-block:: python
+              :name: code-example-parameters
             
                 import paddle
                 import paddle.nn as nn
@@ -1501,16 +1511,16 @@ class Model(object):
         Configures the model before runing.
 
         Args:
-            optimizer (Optimizer|None): Optimizer must be set in training
+            optimizer (Optimizer|None, optional): Optimizer must be set in training
                 and should be a Optimizer instance. It can be None in eval
-                and test mode.
-            loss (Loss|callable function|None): Loss function can
+                and test mode. Default: None.
+            loss (Loss|Callable|None, optional): Loss function can
                 be a `paddle.nn.Layer` instance or any callable function
                 taken the predicted values and ground truth values as input.
-                It can be None when there is no loss.
-            metrics (Metric|list of Metric|None): If metrics is set, all
-                metrics will be calculated and output in train/eval mode.
-            amp_configs (str|dict|None): AMP configurations. If AMP or pure
+                It can be None when there is no loss. Default: None.
+            metrics (Metric|list[Metric]|None, optional): If metrics is set, all
+                metrics will be calculated and output in train/eval mode. Default: None.
+            amp_configs (str|dict|None, optional): AMP configurations. If AMP or pure
                 float16 training is used, the key 'level' of 'amp_configs'
                 should be set to 'O1' or 'O2' respectively. Otherwise, the
                 value of 'level' defaults to 'O0', which means float32
@@ -1526,6 +1536,7 @@ class Model(object):
                 for details. For convenience, 'amp_configs' could be set to
                 'O1' or 'O2' if no more parameters are needed. 'amp_configs'
                 could be None in float32 training. Default: None.
+
         Returns:
             None
         """
@@ -1587,58 +1598,57 @@ class Model(object):
         evaluation will be done at the end of each epoch.
 
         Args:
-            train_data (Dataset|DataLoader): An iterable data loader is used for 
+            train_data (Dataset|DataLoader, optional): An iterable data loader is used for 
                 train. An instance of paddle paddle.io.Dataset or 
                 paddle.io.Dataloader is recomended. Default: None.
-            eval_data (Dataset|DataLoader): An iterable data loader is used for
+            eval_data (Dataset|DataLoader, optional): An iterable data loader is used for
                 evaluation at the end of epoch. If None, will not do evaluation. 
                 An instance of paddle.io.Dataset or paddle.io.Dataloader 
                 is recomended. Default: None.
-            batch_size (int): Integer number. The batch size of train_data
-                and eval_data. When train_data and eval_data are both the
-                instance of Dataloader, this parameter will be ignored.
-                Default: 1.
-            epochs (int): Integer number. The number of epochs to train
-                the model. Default: 1.
-            eval_freq (int): The frequency, in number of epochs, an evalutation
+            batch_size (int, optional): The batch size of train_data and eval_data. When 
+                train_data and eval_data are both the instance of Dataloader, this
+                parameter will be ignored. Default: 1.
+            epochs (int, optional): The number of epochs to train the model. Default: 1.
+            eval_freq (int, optional): The frequency, in number of epochs, an evalutation
                 is performed. Default: 1.
-            log_freq (int): The frequency, in number of steps, the training logs
+            log_freq (int, optional): The frequency, in number of steps, the training logs
                 are printed. Default: 10.
-            save_dir(str|None): The directory to save checkpoint during training.
+            save_dir(str|None, optional): The directory to save checkpoint during training.
                 If None, will not save checkpoint. Default: None.
-            save_freq (int): The frequency, in number of epochs, to save
+            save_freq (int, optional): The frequency, in number of epochs, to save
                 checkpoint. Default: 1.
-            verbose (int): The verbosity mode, should be 0, 1, or 2. 0 = silent,
+            verbose (int, optional): The verbosity mode, should be 0, 1, or 2. 0 = silent,
                 1 = progress bar, 2 = one line per epoch. Default: 2.
-            drop_last (bool): Whether drop the last incomplete batch of
+            drop_last (bool, optional): Whether drop the last incomplete batch of
                 train_data when dataset size is not divisible by the batch size.
                 When train_data is an instance of Dataloader, this parameter
                 will be ignored. Default: False.
-            shuffle (bool): Whther to shuffle train_data. When train_data is
+            shuffle (bool, optional): Whther to shuffle train_data. When train_data is
                 an instance of Dataloader, this parameter will be ignored.
                 Default: True.
-            num_workers (int): The number of subprocess to load data, 0 for no
+            num_workers (int, optional): The number of subprocess to load data, 0 for no
                 subprocess used and loading data in main process.
                 When train_data and eval_data are both the instance of
                 Dataloader, this parameter will be ignored. Default: 0.
-            callbacks (Callback|None): A list of `Callback` instances to apply
-                during training. If None, `ProgBarLogger` and `ModelCheckpoint`
-                are automatically inserted. Default: None.
-            accumulate_grad_batches (int): The number of batches to accumulate gradident 
+            callbacks (Callback|None, optional): A list of `Callback` instances to apply
+                during training. If None, :ref:`api_paddle_callbacks_ProgBarLogger` and
+                :ref:`api_paddle_callbacks_ModelCheckpoint` are automatically inserted. Default: None.
+            accumulate_grad_batches (int, optional): The number of batches to accumulate gradident 
                 during training process before optimizer updates. It can mimic large batch
                 size. Default: 1.
-            num_iters (int|None): Integer number. The number of iterations to train
-                the model. If None, follow `epochs` to train the model, otherwise, train
-                the model `num_iters` times. Default: None.
+            num_iters (int|None, optional): The number of iterations to evaluate the model.
+                If None, evaluate on whole input dataset, otherwise, evaluate `num_iters` times.
+                Default: None.
 
         Returns:
             None
 
         Examples:
-            1. An example use Dataset and set btch size, shuffle in fit.
+            1. An example use Dataset and set batch size, shuffle in fit.
                How to make a batch is done internally.
 
             .. code-block:: python
+              :name: code-example-fit-1
 
                 import paddle
                 import paddle.vision.transforms as T
@@ -1678,6 +1688,7 @@ class Model(object):
                DataLoader.
 
             .. code-block:: python
+              :name: code-example-fit-2
 
                 import paddle
                 import paddle.vision.transforms as T
@@ -1809,23 +1820,23 @@ class Model(object):
             eval_data (Dataset|DataLoader): An iterable data loader is used for
                 evaluation. An instance of paddle.io.Dataset or 
                 paddle.io.Dataloader is recomended.
-            batch_size (int): Integer number. The batch size of train_data
-                and eval_data.  When eval_data is the instance of Dataloader,
-                this argument will be ignored. Default: 1.
-            log_freq (int): The frequency, in number of steps, the eval logs
+            batch_size (int, optional): The batch size of train_data and eval_data.
+                When eval_data is the instance of Dataloader, this argument will be
+                ignored. Default: 1.
+            log_freq (int, optional): The frequency, in number of steps, the eval logs
                 are printed. Default: 10.
-            verbose (int): The verbosity mode, should be 0, 1, or 2. 0 = silent,
+            verbose (int, optional): The verbosity mode, should be 0, 1, or 2. 0 = silent,
                 1 = progress bar, 2 = one line per epoch. Default: 2.
-            num_workers (int): The number of subprocess to load data,
+            num_workers (int, optional): The number of subprocess to load data,
                 0 for no subprocess used and loading data in main process. When
                 train_data and eval_data are both the instance of Dataloader,
                 this parameter will be ignored. Default: 0.
-            callbacks (Callback|None): A list of `Callback` instances to apply
+            callbacks (Callback|None, optional): A list of `Callback` instances to apply
                 during training. If None, `ProgBarLogger` and `ModelCheckpoint`
                 are automatically inserted. Default: None.
-            num_iters (int|None): Integer number. The number of iterations to
-                evaluate the model. If None, evaluate on whole input dataset,
-                otherwise, evaluate `num_iters` times. Default: None.
+            num_iters (int|None, optional): The number of iterations to evaluate the model.
+                If None, evaluate on whole input dataset, otherwise, evaluate `num_iters` times.
+                Default: None.
         Returns:
             dict: Result of metric. The key is the names of Metric,
                 value is a scalar or numpy.array.
@@ -1833,6 +1844,7 @@ class Model(object):
         Examples:
 
           .. code-block:: python
+            :name: code-example-evaluate
 
                 import paddle
                 import paddle.vision.transforms as T
@@ -1851,6 +1863,7 @@ class Model(object):
                 model.prepare(metrics=paddle.metric.Accuracy())
                 result = model.evaluate(val_dataset, batch_size=64)
                 print(result)
+                # {'acc': 0.0699}
         """
 
         if eval_data is not None and isinstance(eval_data, Dataset):
@@ -1912,21 +1925,20 @@ class Model(object):
             test_data (Dataset|DataLoader): An iterable data loader is used for
                 predict. An instance of paddle.io.Dataset or paddle.io.Dataloader
                 is recomended.
-            batch_size (int): Integer number. The batch size of train_data and eval_data.
-                When train_data and eval_data are both the instance of Dataloader, this
-                argument will be ignored. Default: 1.
-            num_workers (int): The number of subprocess to load data, 0 for no subprocess 
-                used and loading data in main process. When train_data and eval_data are
-                both the instance of Dataloader, this argument will be ignored. Default: 0.
-            stack_outputs (bool): Whether stack output field like a batch, as for an output
-                filed of a sample is in shape [X, Y], test_data contains N samples, predict
+            batch_size (int, optional): The batch size of test_data. When test_data is the
+                instance of Dataloader, this argument will be ignored. Default: 1.
+            num_workers (int, optional): The number of subprocess to load data, 0 for no subprocess 
+                used and loading data in main process. When test_data is the instance of Dataloader,
+                this argument will be ignored. Default: 0.
+            stack_outputs (bool, optional): Whether stack output field like a batch, as for an output
+                field of a sample is in shape [X, Y], test_data contains N samples, predict
                 output field will be in shape [N, X, Y] if stack_output is True, and will
-                be a length N list in shape [[X, Y], [X, Y], ....[X, Y]] if stack_outputs
+                be a length N list in shape [[X, Y], [X, Y], ..., [X, Y]] if stack_outputs
                 is False. stack_outputs as False is used for LoDTensor output situation,
                 it is recommended set as True if outputs contains no LoDTensor. Default: False.
-            verbose (int): The verbosity mode, should be 0, 1, or 2. 0 = silent,
+            verbose (int, optional): The verbosity mode, should be 0, 1, or 2. 0 = silent,
                 1 = progress bar, 2 = one line per batch. Default: 1.
-            callbacks(Callback): A Callback instance, default None.
+            callbacks(Callback, optional): A Callback instance, Default: None.
 
         Returns:
             list: output of models.
@@ -1934,6 +1946,7 @@ class Model(object):
         Examples:
 
           .. code-block:: python
+            :name: code-example-predict
 
                 import numpy as np
                 import paddle
@@ -1961,6 +1974,7 @@ class Model(object):
                 model.prepare()
                 result = model.predict(test_dataset, batch_size=64)
                 print(len(result[0]), result[0][0].shape)
+                # 157 (64, 10)
 
                 # declarative mode
                 device = paddle.set_device('cpu')
@@ -1971,6 +1985,7 @@ class Model(object):
 
                 result = model.predict(test_dataset, batch_size=64)
                 print(len(result[0]), result[0][0].shape)
+                # 157 (64, 10)
         """
 
         if test_data is not None and isinstance(test_data, Dataset):
@@ -2164,6 +2179,7 @@ class Model(object):
 
         Examples:
             .. code-block:: python
+              :name: code-example-summary
 
                 import paddle
                 from paddle.static import InputSpec
@@ -2181,6 +2197,7 @@ class Model(object):
 
                 params_info = model.summary()
                 print(params_info)
+                # {'total_params': 61610, 'trainable_params': 61610}
 
         """
         assert (input_size is not None or self._inputs