fix APIs, test=document_preview (#1305)

* fix APIs, test=document_preview

* fix APIs, test=document_preview

doc/fluid/api_cn/metrics_cn/Accuracy_cn.rst

@@ -2,52 +2,59 @@
 
 Accuracy
 -------------------------------
-
 .. py:class:: paddle.fluid.metrics.Accuracy(name=None)
 
-计算多批次的平均准确率。
-https://en.wikipedia.org/wiki/Accuracy_and_precision
+该接口用来计算多个mini-batch的平均准确率。Accuracy对象有两个状态value和weight。Accuracy的定义参照 https://en.wikipedia.org/wiki/Accuracy_and_precision 。
 
 参数:
-    - **name** — 度量标准的名称
+    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
-**代码示例**
+返回：初始化后的 ``Accuracy`` 对象
 
-.. code-block:: python
+返回类型：Accuracy
 
-    import paddle.fluid as fluid
-    # 假设有batch_size = 128
-    batch_size=128
-    accuracy_manager = fluid.metrics.Accuracy()
-    # 假设第一个batch的准确率为0.9
-    batch1_acc = 0.9
-    accuracy_manager.update(value = batch1_acc, weight = batch_size)
-    print("expect accuracy: %.2f, get accuracy: %.2f" % (batch1_acc, accuracy_manager.eval()))
-    # 假设第二个batch的准确率为0.8
-    batch2_acc = 0.8
-    accuracy_manager.update(value = batch2_acc, weight = batch_size)
-    #batch1和batch2的联合准确率为(batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2
-    print("expect accuracy: %.2f, get accuracy: %.2f" % ((batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2, accuracy_manager.eval()))
-    #重置accuracy_manager
-    accuracy_manager.reset()
-    #假设第三个batch的准确率为0.8
-    batch3_acc = 0.8
-    accuracy_manager.update(value = batch3_acc, weight = batch_size)
-    print("expect accuracy: %.2f, get accuracy: %.2f" % (batch3_acc, accuracy_manager.eval()))
+**代码示例**
 
+.. code-block:: python
 
+        import paddle.fluid as fluid
+        # 假设有batch_size = 128
+        batch_size=128
+        accuracy_manager = fluid.metrics.Accuracy()
+        # 假设第一个batch的准确率为0.9
+        batch1_acc = 0.9
+        accuracy_manager.update(value = batch1_acc, weight = batch_size)
+        print("expect accuracy: %.2f, get accuracy: %.2f" % (batch1_acc, accuracy_manager.eval()))
+        # 假设第二个batch的准确率为0.8
+        batch2_acc = 0.8
+        accuracy_manager.update(value = batch2_acc, weight = batch_size)
+        #batch1和batch2的联合准确率为(batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2
+        print("expect accuracy: %.2f, get accuracy: %.2f" % ((batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2, accuracy_manager.eval()))
+        #重置accuracy_manager
+        accuracy_manager.reset()
+        #假设第三个batch的准确率为0.8
+        batch3_acc = 0.8
+        accuracy_manager.update(value = batch3_acc, weight = batch_size)
+        print("expect accuracy: %.2f, get accuracy: %.2f" % (batch3_acc, accuracy_manager.eval()))
 
 .. py:method:: update(value, weight)
 
-更新mini batch的状态。
+该函数使用输入的(value, weight)来累计更新Accuracy对象的对应状态，更新方式如下：
+
+    .. math::
+                   \\ \begin{array}{l}{\text { self. value }+=\text { value } * \text { weight }} \\ {\text { self. weight }+=\text { weight }}\end{array} \\
 
 参数：    
-    - **value** (float|numpy.array) – 每个mini batch的正确率
-    - **weight** (int|float) – batch 大小
+    - **value** (float|numpy.array) – mini-batch的正确率
+    - **weight** (int|float) – mini-batch的大小
 
+返回：无
 
 .. py:method:: eval()
 
-返回所有累计batches的平均准确率（float或numpy.array）。
+该函数计算并返回累计的mini-batches的平均准确率。
+
+返回：累计的mini-batches的平均准确率
 
+返回类型：float或numpy.array
 

doc/fluid/api_cn/metrics_cn/Auc_cn.rst

@@ -2,18 +2,21 @@
 
 Auc
 -------------------------------
-
 .. py:class:: paddle.fluid.metrics.Auc(name, curve='ROC', num_thresholds=4095)
 
-Auc度量用于二分类。参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve  。请注意auc度量是用Python实现的，可能速度略慢。
+**注意**：目前只用Python实现Auc，可能速度略慢
+
+该接口计算Auc，在二分类(binary classification)中广泛使用。相关定义参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。
 
-auc函数创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算AUC。对于离散化AUC曲线，临界值线性间隔设置以便计算召回率和准确率的值，用false positive率的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。
+该接口创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算Auc。为了离散化AUC曲线，使用临界值的线性间隔来计算召回率和准确率的值。用false positive的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。
 
 参数：
-    - **name** - 度量名
-    - **curve** - 将要计算的曲线名的详情，曲线包括ROC（默认）或者PR（Precision-Recall-curve）。
+    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+    - **curve** (str) - 将要计算的曲线名的详情，曲线包括ROC（默认）或者PR（Precision-Recall-curve）。
+
+返回：初始化后的 ``Auc`` 对象
 
-注：目前只用Python实现ROC曲线
+返回类型：Auc
 
 **代码示例**：
 
@@ -43,24 +46,19 @@ auc函数创建四个局部变量true_positives, true_negatives, false_positives
 
 .. py:method:: update(preds, labels)
 
-用给定的预测值和标签更新auc曲线。
+用给定的预测值和标签更新Auc曲线。
 
 参数： 
-    - **preds** – 形状为(batch_size, 2)的numpy数组，preds[i][j]表示将实例i划分为类别j的概率。
-    - **labels** – 形状为(batch_size, 1)的numpy数组，labels[i]为0或1，代表实例i的标签。
+    - **preds** (numpy.array) - 维度为[batch_size, 2]，preds[i][j]表示将实例i划分为类别j的概率。
+    - **labels** (numpy.array) - 维度为[batch_size, 1]，labels[i]为0或1，代表实例i的标签。
 
+返回：无
 
 .. py:method:: eval()
 
-返回auc曲线下的区域（一个float值）。
-
-
-
-
-
-
-
-
+该函数计算并返回Auc值。
 
+返回：Auc值
 
+返回类型：float
 

doc/fluid/api_cn/metrics_cn/ChunkEvaluator_cn.rst

@@ -4,14 +4,21 @@ ChunkEvaluator
 -------------------------------
 
 .. py:class:: paddle.fluid.metrics.ChunkEvaluator(name=None)
+该接口使用mini-batch的chunk_eval累计的counter numbers，来计算准确率、召回率和F1值。ChunkEvaluator有三个状态num_infer_chunks，num_label_chunks和num_correct_chunks，分别对应语块数目、标签中的语块数目、正确识别的语块数目。对于chunking的基础知识，请参考 https://www.aclweb.org/anthology/N01-1025 。ChunkEvalEvaluator计算块检测（chunk detection）的准确率，召回率和F1值，支持IOB, IOE, IOBES和IO标注方案。
 
-用mini-batch的chunk_eval累计counter numbers，用累积的counter numbers计算准确率、召回率和F1值。对于chunking的基础知识，请参考 .. _Chunking with Support Vector Machines: https://aclanthology.info/pdf/N/N01/N01-1025.pdf 。ChunkEvalEvaluator计算块检测（chunk detection）的准确率，召回率和F1值，支持IOB, IOE, IOBES和IO标注方案。
+参数：
+    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+
+返回：初始化后的 ``ChunkEvaluator`` 对象
+
+返回类型：ChunkEvaluator
 
 **代码示例**：
 
 .. code-block:: python
 
         import paddle.fluid as fluid
+
         # 初始化chunck-level的评价管理。
         metric = fluid.metrics.ChunkEvaluator()
         
@@ -37,16 +44,23 @@ ChunkEvaluator
     
 .. py:method:: update(num_infer_chunks, num_label_chunks, num_correct_chunks)
 
-基于layers.chunk_eval()输出更新状态（state)输出
+该函数使用输入的(num_infer_chunks, num_label_chunks, num_correct_chunks)来累计更新ChunkEvaluator对象的对应状态，更新方式如下：
+    
+    .. math:: 
+                   \\ \begin{array}{l}{\text { self. num_infer_chunks }+=\text { num_infer_chunks }} \\ {\text { self. num_Label_chunks }+=\text { num_label_chunks }} \\ {\text { self. num_correct_chunks }+=\text { num_correct_chunks }}\end{array} \\
 
 参数:
-    - **num_infer_chunks** (int|numpy.array): 给定minibatch的Interface块数。
-    - **num_label_chunks** (int|numpy.array): 给定minibatch的Label块数。
-    - **num_correct_chunks** （int|float|numpy.array）: 给定minibatch的Interface和Label的块数
-
+    - **num_infer_chunks** (int|numpy.array) – 给定mini-batch的语块数目。
+    - **num_label_chunks** (int|numpy.array) - 给定mini-batch的标签中的语块数目。
+    - **num_correct_chunks** （int|numpy.array）— 给定mini-batch的正确识别的语块数目。
 
+返回：无
 
+.. py:method:: eval()
 
+该函数计算并返回准确率，召回率和F1值。
 
+返回：准确率，召回率和F1值
 
+返回类型：float