English API Docs Optimization Part 1 (#24536)

CaiZixin · swtkiwi · web-flow · commit 86ca31ab5840 · 2020-05-14T15:44:17.000+08:00
* test=develop, test=document_fix

* test=develop, test=document_fix

Co-authored-by: swtkiwi &lt;1208425345@qq.com&gt;
diff --git a/python/paddle/fluid/backward.py b/python/paddle/fluid/backward.py
@@ -1196,6 +1196,8 @@ def append_backward(loss,
                     callbacks=None,
                     checkpoints=None):
     """
+    :api_attr: Static Graph
+
     This function appends backward part to main_program.
 
     A complete neural network training is made up of forward and backward
@@ -1724,6 +1726,8 @@ def calc_gradient(targets, inputs, target_gradients=None, no_grad_set=None):
 
 def gradients(targets, inputs, target_gradients=None, no_grad_set=None):
     """
+    :api_attr: Static Graph
+    
     Backpropagate the gradients of targets to inputs.
 
     Args:
diff --git a/python/paddle/fluid/clip.py b/python/paddle/fluid/clip.py
@@ -158,6 +158,10 @@ def _create_operators(self, param, grad):
 
 class GradientClipByValue(GradientClipBase):
     """
+    :alias_main: paddle.nn.GradientClipByValue
+	:alias: paddle.nn.GradientClipByValue,paddle.nn.clip.GradientClipByValue
+	:old_api: paddle.fluid.clip.GradientClipByValue
+
     Limit the value of multi-dimensional Tensor :math:`X` to the range [min, max].
     
     - Any values less than min are set to ``min``.
@@ -296,6 +300,10 @@ def _create_operators(self, param, grad):
 
 class GradientClipByNorm(GradientClipBase):
     """
+    :alias_main: paddle.nn.GradientClipByNorm
+	:alias: paddle.nn.GradientClipByNorm,paddle.nn.clip.GradientClipByNorm
+	:old_api: paddle.fluid.clip.GradientClipByNorm
+
     Limit the l2 norm of multi-dimensional Tensor :math:`X` to ``clip_norm`` .
     
     - If the l2 norm of :math:`X` is greater than ``clip_norm`` , :math:`X` will be compressed by a ratio.
@@ -447,6 +455,10 @@ def _create_operators(self, param, grad):
 
 class GradientClipByGlobalNorm(GradientClipBase):
     """
+    :alias_main: paddle.nn.GradientClipByGlobalNorm
+	:alias: paddle.nn.GradientClipByGlobalNorm,paddle.nn.clip.GradientClipByGlobalNorm
+	:old_api: paddle.fluid.clip.GradientClipByGlobalNorm
+
     Given a list of Tensor :math:`t\_list` , calculate the global norm for the elements of all tensors in 
     :math:`t\_list` , and limit it to ``clip_norm`` .
     
@@ -691,6 +703,8 @@ def _create_operators(self, param, grad):
 @framework.dygraph_not_support
 def set_gradient_clip(clip, param_list=None, program=None):
     """
+    :api_attr: Static Graph
+    
     Warning:
     
         This API must be used after building network, and before ``minimize`` , 
diff --git a/python/paddle/fluid/compiler.py b/python/paddle/fluid/compiler.py
@@ -86,6 +86,8 @@ def _has_optimizer_in_control_flow(program):
 
 class CompiledProgram(object):
     """
+    :api_attr: Static Graph
+    
     The CompiledProgram is used to transform a program or graph for
     various optimizations according to the configuration of build_strategy,
     for example, the operators' fusion in the computation graph, memory
diff --git a/python/paddle/fluid/data.py b/python/paddle/fluid/data.py
@@ -24,6 +24,11 @@
 
 def data(name, shape, dtype='float32', lod_level=0):
     """
+    :api_attr: Static Graph
+	:alias_main: paddle.nn.data
+	:alias: paddle.nn.data,paddle.nn.input.data
+	:old_api: paddle.fluid.data
+
     **Data Layer**
 
     This function creates a variable on the global block. The global variable
diff --git a/python/paddle/fluid/data_feed_desc.py b/python/paddle/fluid/data_feed_desc.py
@@ -20,6 +20,8 @@
 
 class DataFeedDesc(object):
     """
+    :api_attr: Static Graph
+    
     Datafeed descriptor, describing input training data format. This class is
     currently only used for AsyncExecutor (See comments for class AsyncExecutor
     for a brief introduction)
diff --git a/python/paddle/fluid/data_feeder.py b/python/paddle/fluid/data_feeder.py
@@ -211,6 +211,8 @@ def __call__(self):
 
 class DataFeeder(object):
     """
+    :api_attr: Static Graph
+    
     DataFeeder converts the data that returned by a reader into a data
     structure that can feed into Executor. The reader is usually a 
     python generator that returns a list of mini-batch data entries. 
diff --git a/python/paddle/fluid/dataset.py b/python/paddle/fluid/dataset.py
@@ -728,6 +728,8 @@ def global_shuffle(self, fleet=None, thread_num=12):
 
     def release_memory(self):
         """
+        :api_attr: Static Graph
+        
         Release InMemoryDataset memory data, when data will not be used again.
 
         Examples:
diff --git a/python/paddle/fluid/dygraph/base.py b/python/paddle/fluid/dygraph/base.py
@@ -111,6 +111,10 @@ def enabled():
 
 def enable_dygraph(place=None):
     """
+    :alias_main: paddle.enable_dygraph
+	:alias: paddle.enable_dygraph,paddle.enable_imperative.enable_dygraph
+	:old_api: paddle.fluid.dygraph.base.enable_dygraph
+
     This function enables dynamic graph mode.
 
     Parameters:
@@ -141,6 +145,10 @@ def enable_dygraph(place=None):
 
 def disable_dygraph():
     """
+    :alias_main: paddle.disable_dygraph
+	:alias: paddle.disable_dygraph,paddle.disable_imperative.disable_dygraph
+	:old_api: paddle.fluid.dygraph.base.disable_dygraph
+
     This function disables dynamic graph mode.
 
     return:
@@ -178,6 +186,8 @@ def _switch_tracer_mode_guard_(is_train=True):
 
 def no_grad(func=None):
     """
+    :api_attr: imperative
+
     Create a context which disables dygraph gradient calculation.
     In this mode, the result of every computation will have `stop_gradient=True`.
 
@@ -236,6 +246,8 @@ def __impl__(func, *args, **kwargs):
 @signature_safe_contextmanager
 def guard(place=None):
     """
+    :api_attr: imperative
+
     This context will create a dygraph context for dygraph to run, using python ``with`` statement.
 
     Parameters:
@@ -520,6 +532,8 @@ def check_in_out(in_out_list, name):
 @framework.dygraph_only
 def to_variable(value, name=None, zero_copy=None):
     """
+    :api_attr: imperative
+
     The API will create a ``Variable`` or ``ComplexVariable`` object from 
     numpy\.ndarray, Variable or ComplexVariable object.
 
diff --git a/python/paddle/fluid/dygraph/checkpoint.py b/python/paddle/fluid/dygraph/checkpoint.py
@@ -32,6 +32,8 @@
 @dygraph_only
 def save_dygraph(state_dict, model_path):
     '''
+    :api_attr: imperative
+
     Save Layer's state_dict to disk. This will generate a file with suffix ".pdparams"
     
     The state_dict is get from Layers.state_dict function
@@ -95,6 +97,8 @@ def save_dygraph(state_dict, model_path):
 @dygraph_only
 def load_dygraph(model_path, keep_name_table=False):
     '''
+    :api_attr: imperative
+    
     Load parameter state_dict from disk.
 
     Args:
diff --git a/python/paddle/fluid/dygraph/jit.py b/python/paddle/fluid/dygraph/jit.py
@@ -203,6 +203,8 @@ def _trace(layer,
 
 class TracedLayer(object):
     """
+    :api_attr: imperative
+    
     TracedLayer is used to convert a forward dygraph model to a static
     graph model. This is mainly used to save the dygraph model for online
     inference using C++. Besides, users can also do inference in Python
diff --git a/python/paddle/fluid/dygraph/layers.py b/python/paddle/fluid/dygraph/layers.py
@@ -58,7 +58,12 @@ def remove(self):
 
 
 class Layer(core.Layer):
-    """Dynamic graph Layer based on OOD, includes the parameters of the layer, the structure of the forward graph and so on.
+    """
+    :alias_main: paddle.nn.Layer
+	:alias: paddle.nn.Layer
+	:old_api: paddle.fluid.dygraph.layers.Layer
+
+    Dynamic graph Layer based on OOD, includes the parameters of the layer, the structure of the forward graph and so on.
 
     Parameters:
         name_scope (str, optional): prefix name used by the layer to name parameters.
diff --git a/python/paddle/fluid/dygraph/learning_rate_scheduler.py b/python/paddle/fluid/dygraph/learning_rate_scheduler.py
@@ -69,6 +69,8 @@ def step(self):
 
 class PiecewiseDecay(LearningRateDecay):
     """
+    :api_attr: imperative
+    
     Piecewise decay scheduler.
 
     The algorithm can be described as the code below.
@@ -128,6 +130,8 @@ def step(self):
 
 class NaturalExpDecay(LearningRateDecay):
     """
+    :api_attr: imperative
+
     Applies natural exponential decay to the initial learning rate.
     
     The algorithm can be described as following.
@@ -207,6 +211,8 @@ def step(self):
 
 class ExponentialDecay(LearningRateDecay):
     """
+    :api_attr: imperative
+
     Applies exponential decay to the learning rate.
 
     The algorithm can be described as following.
@@ -287,6 +293,8 @@ def step(self):
 
 class InverseTimeDecay(LearningRateDecay):
     """
+    :api_attr: imperative
+
     Applies inverse time decay to the initial learning rate.
 
     The algorithm can be described as following.
@@ -363,6 +371,8 @@ def step(self):
 
 class PolynomialDecay(LearningRateDecay):
     """
+    :api_attr: imperative
+
     Applies polynomial decay to the initial learning rate.
 
     The algorithm can be described as following.
@@ -455,6 +465,8 @@ def step(self):
 
 class CosineDecay(LearningRateDecay):
     """
+    :api_attr: imperative
+
     Applies cosine decay to the learning rate.
 
     The algorithm can be described as following.
@@ -511,6 +523,8 @@ def step(self):
 
 class NoamDecay(LearningRateDecay):
     """
+    :api_attr: imperative
+
     Applies Noam decay to the initial learning rate. 
 
     The algorithm can be described as following.
diff --git a/python/paddle/fluid/dygraph/nn.py b/python/paddle/fluid/dygraph/nn.py
@@ -696,6 +696,10 @@ def forward(self, input):
 
 class Pool2D(layers.Layer):
     """
+    :alias_main: paddle.nn.Pool2D
+	:alias: paddle.nn.Pool2D,paddle.nn.layer.Pool2D,paddle.nn.layer.common.Pool2D
+	:old_api: paddle.fluid.dygraph.Pool2D
+
     This interface is used to construct a callable object of the ``Pool2D`` class.
     For more details, refer to code examples.
     The pooling2d operation calculates the output based on the input, pool_type and pool_size, pool_stride,
@@ -867,6 +871,10 @@ def forward(self, input):
 
 class Linear(layers.Layer):
     """
+    :alias_main: paddle.nn.Linear
+	:alias: paddle.nn.Linear,paddle.nn.layer.Linear,paddle.nn.layer.common.Linear
+	:old_api: paddle.fluid.dygraph.Linear
+    
     Fully-connected linear transformation layer:
 
     .. math::
@@ -1100,6 +1108,10 @@ def forward(self, input):
 
 class BatchNorm(layers.Layer):
     """
+    :alias_main: paddle.nn.BatchNorm
+	:alias: paddle.nn.BatchNorm,paddle.nn.layer.BatchNorm,paddle.nn.layer.norm.BatchNorm
+	:old_api: paddle.fluid.dygraph.BatchNorm
+
     This interface is used to construct a callable object of the ``BatchNorm`` class.
     For more details, refer to code examples.
     It implements the function of the Batch Normalization Layer and can be used 
@@ -1443,6 +1455,10 @@ def forward(self, input):
 
 class Embedding(layers.Layer):
     """
+    :alias_main: paddle.nn.Embedding
+	:alias: paddle.nn.Embedding,paddle.nn.layer.Embedding,paddle.nn.layer.common.Embedding
+	:old_api: paddle.fluid.dygraph.Embedding
+
     **Embedding Layer**
 
     This interface is used to construct a callable object of the ``Embedding`` class.
@@ -1599,6 +1615,10 @@ def forward(self, input):
 
 class LayerNorm(layers.Layer):
     """
+    :alias_main: paddle.nn.LayerNorm
+	:alias: paddle.nn.LayerNorm,paddle.nn.layer.LayerNorm,paddle.nn.layer.norm.LayerNorm
+	:old_api: paddle.fluid.dygraph.LayerNorm
+
     This interface is used to construct a callable object of the ``LayerNorm`` class.
     For more details, refer to code examples.
     It implements the function of the Layer Normalization Layer and can be applied to mini-batch input data.
@@ -2289,6 +2309,10 @@ def forward(self, input):
 
 class BilinearTensorProduct(layers.Layer):
     """
+    :alias_main: paddle.nn.BilinearTensorProduct
+	:alias: paddle.nn.BilinearTensorProduct,paddle.nn.layer.BilinearTensorProduct,paddle.nn.layer.common.BilinearTensorProduct
+	:old_api: paddle.fluid.dygraph.BilinearTensorProduct
+
     **Add Bilinear Tensor Product Layer**
 
     This layer performs bilinear tensor product on two inputs.
@@ -2809,6 +2833,10 @@ def forward(self, input):
 
 class GroupNorm(layers.Layer):
     """
+    :alias_main: paddle.nn.GroupNorm
+	:alias: paddle.nn.GroupNorm,paddle.nn.layer.GroupNorm,paddle.nn.layer.norm.GroupNorm
+	:old_api: paddle.fluid.dygraph.GroupNorm
+
     This interface is used to construct a callable object of the ``GroupNorm`` class.
     For more details, refer to code examples.
     It implements the function of the Group Normalization Layer.
@@ -2909,6 +2937,10 @@ def forward(self, input):
 
 class SpectralNorm(layers.Layer):
     """
+    :alias_main: paddle.nn.SpectralNorm
+	:alias: paddle.nn.SpectralNorm,paddle.nn.layer.SpectralNorm,paddle.nn.layer.norm.SpectralNorm
+	:old_api: paddle.fluid.dygraph.SpectralNorm
+
     This interface is used to construct a callable object of the ``SpectralNorm`` class.
     For more details, refer to code examples. It implements the function of the Spectral Normalization Layer.
     This layer calculates the spectral normalization value of weight parameters of
diff --git a/python/paddle/fluid/dygraph/parallel.py b/python/paddle/fluid/dygraph/parallel.py
@@ -28,6 +28,9 @@
 
 
 def prepare_context(strategy=None):
+    '''
+    :api_attr: imperative
+    '''
     if strategy is None:
         strategy = ParallelStrategy()
         strategy.nranks = Env().nranks
diff --git a/python/paddle/fluid/dygraph/tracer.py b/python/paddle/fluid/dygraph/tracer.py
@@ -23,6 +23,8 @@
 
 class Tracer(core.Tracer):
     """
+    :api_attr: imperative
+    
     Tracer is used to execute and record the operators executed, to construct the 
     computation graph in dygraph model. Tracer has two mode, :code:`train_mode`
     and :code:`eval_mode`. In :code:`train_mode`, Tracer would add backward network 
diff --git a/python/paddle/fluid/executor.py b/python/paddle/fluid/executor.py
@@ -40,6 +40,8 @@
 
 def global_scope():
     """
+    :api_attr: Static Graph
+
     Get the global/default scope instance. There are a lot of APIs use
     :code:`global_scope` as its default value, e.g., :code:`Executor.run`
 
@@ -68,6 +70,8 @@ def _switch_scope(scope):
 @signature_safe_contextmanager
 def scope_guard(scope):
     """
+    :api_attr: Static Graph
+    
     This function switches scope through python `with` statement.
     Scope records the mapping between variable names and variables ( :ref:`api_guide_Variable` ),
     similar to brackets in programming languages.
@@ -456,6 +460,8 @@ def handler(self, res_dict):
 
 class Executor(object):
     """
+    :api_attr: Static Graph
+
     An Executor in Python, supports single/multiple-GPU running,
     and single/multiple-CPU running.
 
diff --git a/python/paddle/fluid/framework.py b/python/paddle/fluid/framework.py
diff --git a/python/paddle/fluid/input.py b/python/paddle/fluid/input.py
diff --git a/python/paddle/fluid/io.py b/python/paddle/fluid/io.py
diff --git a/python/paddle/fluid/layers/control_flow.py b/python/paddle/fluid/layers/control_flow.py
diff --git a/python/paddle/fluid/layers/loss.py b/python/paddle/fluid/layers/loss.py
diff --git a/python/paddle/fluid/layers/nn.py b/python/paddle/fluid/layers/nn.py
