Repair api example (#17221)

Fix the following API examples:

paddle.fluid.scope_guard
paddle.fluid.backward.append_backward
paddle.fluid.cpu_places
paddle.fluid.cuda_pinned_places
paddle.fluid.cuda_places
paddle.fluid.in_dygraph_mode
paddle.fluid.CUDAPlace
paddle.fluid.CPUPlace
paddle.fluid.CUDAPinnedPlace

paddle/fluid/API.spec

@@ -10,17 +10,17 @@ paddle.fluid.default_startup_program (ArgSpec(args=[], varargs=None, keywords=No
 paddle.fluid.default_main_program (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', '5430f54ab4895f9f47db6bebbaf71659'))
 paddle.fluid.program_guard (ArgSpec(args=['main_program', 'startup_program'], varargs=None, keywords=None, defaults=(None,)), ('document', 'ae5f806f082cfaeaa5194cacc253a5e4'))
 paddle.fluid.name_scope (ArgSpec(args=['prefix'], varargs=None, keywords=None, defaults=(None,)), ('document', '61660461e1f44e0480ca22fa8a482c41'))
-paddle.fluid.cuda_places (ArgSpec(args=['device_ids'], varargs=None, keywords=None, defaults=(None,)), ('document', '7d9a51fc9cf3c5245b5227080a8064c3'))
-paddle.fluid.cpu_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', '4c0cd83f0b401fc2ff84c70974e5d210'))
-paddle.fluid.cuda_pinned_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', 'd0c3ebd813c39958c92b78e3eef7e912'))
-paddle.fluid.in_dygraph_mode (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', 'f06314a1cb30c96b5808dde2219c2dae'))
+paddle.fluid.cuda_places (ArgSpec(args=['device_ids'], varargs=None, keywords=None, defaults=(None,)), ('document', '7f3068b82fc427bfa04b1af953610992'))
+paddle.fluid.cpu_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', '8b674e9a7ac7944c27fd853b675c2cb2'))
+paddle.fluid.cuda_pinned_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', 'cc83b6c5ba8be38ff3ee87e9cec9de5f'))
+paddle.fluid.in_dygraph_mode (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', 'eddb7a1f0083dcc70e9f6c71ee003cb9'))
 paddle.fluid.Executor.__init__ (ArgSpec(args=['self', 'place'], varargs=None, keywords=None, defaults=None), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
 paddle.fluid.Executor.close (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '3a584496aa1343f36eebf3c46b323a74'))
 paddle.fluid.Executor.infer_from_dataset (ArgSpec(args=['self', 'program', 'dataset', 'scope', 'thread', 'debug', 'fetch_list', 'fetch_info', 'print_period'], varargs=None, keywords=None, defaults=(None, None, None, 0, False, None, None, 100)), ('document', '9c7decb955b9c4f718114179c8985581'))
 paddle.fluid.Executor.run (ArgSpec(args=['self', 'program', 'feed', 'fetch_list', 'feed_var_name', 'fetch_var_name', 'scope', 'return_numpy', 'use_program_cache'], varargs=None, keywords=None, defaults=(None, None, None, 'feed', 'fetch', None, True, False)), ('document', '4cfcd9c15b766a51b584cc46d38f1ad8'))
 paddle.fluid.Executor.train_from_dataset (ArgSpec(args=['self', 'program', 'dataset', 'scope', 'thread', 'debug', 'fetch_list', 'fetch_info', 'print_period'], varargs=None, keywords=None, defaults=(None, None, None, 0, False, None, None, 100)), ('document', 'd521011d79e71080fe9b5bb179b43518'))
 paddle.fluid.global_scope (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', 'f65788d9ead293ada47551339df12203'))
-paddle.fluid.scope_guard (ArgSpec(args=['scope'], varargs=None, keywords=None, defaults=None), ('document', 'e480208ccc0c9abf084867206dab4d2c'))
+paddle.fluid.scope_guard (ArgSpec(args=['scope'], varargs=None, keywords=None, defaults=None), ('document', '6e19f92e2f185320a3a86b77e85eb3b3'))
 paddle.fluid.DistributeTranspiler.__init__ (ArgSpec(args=['self', 'config'], varargs=None, keywords=None, defaults=(None,)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
 paddle.fluid.DistributeTranspiler.get_pserver_program (ArgSpec(args=['self', 'endpoint'], varargs=None, keywords=None, defaults=None), ('document', '292ab72977afbe58e6a3bde175452680'))
 paddle.fluid.DistributeTranspiler.get_pserver_programs (ArgSpec(args=['self', 'endpoint'], varargs=None, keywords=None, defaults=None), ('document', '78f4949aedf317666a89ca74b3748ba8'))
@@ -509,7 +509,7 @@ paddle.fluid.optimizer.DGCMomentumOptimizer.apply_optimize (ArgSpec(args=['self'
 paddle.fluid.optimizer.DGCMomentumOptimizer.backward (ArgSpec(args=['self', 'loss', 'startup_program', 'parameter_list', 'no_grad_set', 'callbacks'], varargs=None, keywords=None, defaults=(None, None, None, None)), ('document', 'ba3a113d0229ff7bc9d39bda0a6d947f'))
 paddle.fluid.optimizer.DGCMomentumOptimizer.get_opti_var_name_list (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
 paddle.fluid.optimizer.DGCMomentumOptimizer.minimize (ArgSpec(args=['self', 'loss', 'startup_program', 'parameter_list', 'no_grad_set'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', '35fd5d3330c97903528c7e0dacc7f6ea'))
-paddle.fluid.backward.append_backward (ArgSpec(args=['loss', 'parameter_list', 'no_grad_set', 'callbacks'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', '1a79bd7d10ae54ca763ec81bca36ba24'))
+paddle.fluid.backward.append_backward (ArgSpec(args=['loss', 'parameter_list', 'no_grad_set', 'callbacks'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', '08a5dd9f6f376ff3d55e0b1d92115cbd'))
 paddle.fluid.regularizer.L1DecayRegularizer.__init__ (ArgSpec(args=['self', 'regularization_coeff'], varargs=None, keywords=None, defaults=(0.0,)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
 paddle.fluid.regularizer.L2DecayRegularizer.__init__ (ArgSpec(args=['self', 'regularization_coeff'], varargs=None, keywords=None, defaults=(0.0,)), ('document', '6adf97f83acf6453d4a6a4b1070f3754'))
 paddle.fluid.LoDTensor.__init__ 1. __init__(self: paddle.fluid.core.LoDTensor, arg0: List[List[int]]) -> None  2. __init__(self: paddle.fluid.core.LoDTensor) -> None

paddle/fluid/pybind/pybind.cc

@@ -868,6 +868,12 @@ All parameter, weight, gradient are variables in Paddle.
     CUDAPlace is a descriptor of a device. It represents a GPU, and each CUDAPlace
     has a dev_id to indicate the number of cards represented by the current CUDAPlace.
     The memory of CUDAPlace with different dev_id is not accessible.
+
+    Examples:
+        .. code-block:: python
+
+          gpu_place = fluid.CUDAPlace(0)
+
         )DOC")
       .def("__init__",
            [](platform::CUDAPlace &self, int dev_id) {
@@ -892,6 +898,12 @@ All parameter, weight, gradient are variables in Paddle.
   py::class_<paddle::platform::CPUPlace>(m, "CPUPlace", R"DOC(
     CPUPlace is a descriptor of a device. It represents a CPU, and the memory
     CPUPlace can be accessed by CPU.
+
+    Examples:
+        .. code-block:: python
+
+          cpu_place = fluid.CPUPlace()
+
         )DOC")
       .def(py::init<>())
       .def("_type", &PlaceIndex<platform::CPUPlace>)
@@ -905,6 +917,12 @@ All parameter, weight, gradient are variables in Paddle.
   py::class_<paddle::platform::CUDAPinnedPlace>(m, "CUDAPinnedPlace", R"DOC(
     CUDAPinnedPlace is a descriptor of a device. The memory of CUDAPinnedPlace
     can be accessed by GPU and CPU.
+
+    Examples:
+        .. code-block:: python
+
+          place = fluid.CUDAPinnedPlace()
+
         )DOC")
       .def("__init__",
            [](platform::CUDAPinnedPlace &self) {

python/paddle/fluid/backward.py

@@ -457,7 +457,13 @@ def append_backward(loss, parameter_list=None, no_grad_set=None,
         .. code-block:: python
 
             # network configuration code
-            # ...
+            # loss from ...
+            x = fluid.layers.data(name='x', shape=[13], dtype='float32')
+            y = fluid.layers.data(name='y', shape=[1], dtype='float32')
+
+            y_predict = fluid.layers.fc(input=x, size=1, act=None)
+            loss = fluid.layers.square_error_cost(input=y_predict, label=y)
+
             avg_loss = fluid.layers.mean(loss)
             param_grad_list = fluid.backward.append_backward(loss=avg_loss)
     """

python/paddle/fluid/executor.py

@@ -66,20 +66,20 @@ def scope_guard(scope):
     Change the global/default scope instance by Python `with` statement. All
     variable in runtime will assigned to the new scope.
 
+    Args:
+        scope: The new global/default scope.
+
     Examples:
         .. code-block:: python
 
-          import paddle.fluid as fluid
-          import numpy
-
-          new_scope = fluid.Scope()
-          with fluid.scope_guard(new_scope):
-              fluid.global_scope().var("data").get_tensor().set(numpy.ones((2, 2)), fluid.CPUPlace())
-          numpy.array(new_scope.find_var("data").get_tensor())
+            import numpy
 
-    Args:
-        scope: The new global/default scope.
+            new_scope = fluid.Scope()
+            with fluid.scope_guard(new_scope):
+                 fluid.global_scope().var("data").get_tensor().set(numpy.ones((2, 2)), fluid.CPUPlace())
+            numpy.array(new_scope.find_var("data").get_tensor())
     """
+
     ex = _switch_scope(scope)
     yield
     _switch_scope(ex)

python/paddle/fluid/framework.py

@@ -81,9 +81,19 @@ _dygraph_current_expected_place_ = None
 
 
 def in_dygraph_mode():
-    '''
-    Returns(bool): True if the program is running in dynamic graph mode
-    '''
+    """
+    Check program status(tracer), Whether it runs in dygraph mode or not
+
+    Returns:
+        out (boolean): True if the program is running in dynamic graph mode
+
+    Examples:
+        .. code-block:: python
+
+            if fluid.in_dygraph_mode():
+                pass
+
+    """
     return _dygraph_tracer_ is not None
 
 
@@ -100,7 +110,7 @@ def _cpu_num():
 
 
 def cuda_places(device_ids=None):
-    '''
+    """
     Create a list of :code:`fluid.CUDAPlace` objects.
 
     If :code:`device_ids` is None, environment variable of
@@ -120,7 +130,13 @@ def cuda_places(device_ids=None):
 
     Returns:
         out (list(fluid.CUDAPlace)): gpu place list.
-    '''
+
+    Examples:
+        .. code-block:: python
+
+            cuda_places = fluid.cuda_places()
+
+    """
     assert core.is_compiled_with_cuda(), \
         "Not compiled with CUDA"
     if device_ids is None:
@@ -135,7 +151,7 @@ def cuda_places(device_ids=None):
 
 
 def cpu_places(device_count=None):
-    '''
+    """
     Create a list of :code:`fluid.CPUPlace` objects.
     
     If :code:`device_count` is None, the device count would
@@ -148,14 +164,20 @@ def cpu_places(device_count=None):
 
     Returns:
         out (list(fluid.CPUPlace)): cpu place list.
-    '''
+
+    Examples:
+        .. code-block:: python
+
+            cpu_places = fluid.cpu_places()
+    """
+
     if device_count is None:
         device_count = _cpu_num()
     return [core.CPUPlace()] * device_count
 
 
 def cuda_pinned_places(device_count=None):
-    '''
+    """
     Create a list of :code:`fluid.CUDAPinnedPlace` objects.
 
     If :code:`device_count` is None, the device count would
@@ -168,7 +190,15 @@ def cuda_pinned_places(device_count=None):
 
     Returns:
         out (list(fluid.CUDAPinnedPlace)): cuda pinned place list.
-    '''
+
+    Examples:
+        .. code-block:: python
+
+            cuda_pinned_places_cpu_num = fluid.cuda_pinned_places()
+            # or
+            cuda_pinned_places = fluid.cuda_pinned_places(1)
+
+    """
     assert core.is_compiled_with_cuda(), \
         "Not compiled with CUDA"
     if device_count is None: