From 79806e6e1b421eb58f169f85645cd5799c10ce2d Mon Sep 17 00:00:00 2001
From: Huihuang Zheng <zhhsplendid@gmail.com>
Date: Mon, 9 Dec 2019 21:00:46 +0800
Subject: [PATCH] Add Chinese Doc for cond API (#1648)

* Add Chinese Doc for cond API
---
 doc/fluid/api/layers.rst               |  1 +
 doc/fluid/api_cn/layers_cn.rst         |  1 +
 doc/fluid/api_cn/layers_cn/cond_cn.rst | 86 ++++++++++++++++++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 doc/fluid/api_cn/layers_cn/cond_cn.rst

diff --git a/doc/fluid/api/layers.rst b/doc/fluid/api/layers.rst
index 843015c32..b59b41af2 100644
--- a/doc/fluid/api/layers.rst
+++ b/doc/fluid/api/layers.rst
@@ -46,6 +46,7 @@ fluid.layers
     layers/clip_by_norm.rst
     layers/collect_fpn_proposals.rst
     layers/concat.rst
+    layers/cond.rst
     layers/continuous_value_model.rst
     layers/conv2d.rst
     layers/conv2d_transpose.rst
diff --git a/doc/fluid/api_cn/layers_cn.rst b/doc/fluid/api_cn/layers_cn.rst
index 4679a5eac..94090e0d0 100644
--- a/doc/fluid/api_cn/layers_cn.rst
+++ b/doc/fluid/api_cn/layers_cn.rst
@@ -51,6 +51,7 @@ fluid.layers
     layers_cn/clip_cn.rst
     layers_cn/collect_fpn_proposals_cn.rst
     layers_cn/concat_cn.rst
+    layers_cn/cond_cn.rst
     layers_cn/continuous_value_model_cn.rst
     layers_cn/conv2d_cn.rst
     layers_cn/conv2d_transpose_cn.rst
diff --git a/doc/fluid/api_cn/layers_cn/cond_cn.rst b/doc/fluid/api_cn/layers_cn/cond_cn.rst
new file mode 100644
index 000000000..901a1a14b
--- /dev/null
+++ b/doc/fluid/api_cn/layers_cn/cond_cn.rst
@@ -0,0 +1,86 @@
+.. _cn_api_fluid_layers_cond:
+
+cond
+-------------------------------
+
+.. py:function:: paddle.fluid.layers.cond(pred, true_fn=None, false_fn=None, name=None)
+
+如果 ``pred`` 是 ``True`` ，该API返回 ``true_fn()`` ，否则返回 ``false_fn()`` 。
+用户如果不想在 ``callable`` 中做任何事，可以把 ``true_fn`` 或 ``false_fn`` 设为 ``None`` ，此时本API会把该 ``callable`` 视为简单返回 ``None`` 。
+
+``true_fn`` 和 ``false_fn`` 需要返回同样嵌套结构（nest structure）的Tensor，如果不想返回任何值也可都返回 ``None`` 。
+PaddlePaddle里Tensor的嵌套结构是指一个Tensor，或者Tensor的元组（tuple），或者Tensor的列表（list）。
+
+.. note::
+    1. 因为PaddlePaddle的静态图数据流， ``true_fn`` 和 ``false_fn`` 返回的元组必须形状相同，但是里面的Tensor形状可以不同。
+    2. 不论运行哪个分支，在 ``true_fn`` 和 ``false_fn`` 外创建的Tensor和Op都会被运行，即PaddlePaddle并不是惰性语法（lazy semantics）。例如
+
+       .. code-block:: python
+                  
+            import paddle.fluid as fluid
+            a = fluid.data(name='a', shape=[-1, 1], dtype='float32')
+            b = fluid.data(name='b', shape=[-1, 1], dtype='float32')
+            c = a * b
+            out = fluid.layers.cond(a < b, lambda: a + c, lambda: b * b)
+
+       不管 ``a < b`` 是否成立， ``c = a * b`` 都会被运行。
+
+参数：
+    - **pred** (Variable) - 一个形状为[1]的布尔型（boolean）的Tensor，该布尔值决定要返回 ``true_fn`` 还是 ``false_fn`` 的运行结果。
+    - **true_fn** (callable) - 一个当 ``pred`` 是 ``True`` 时被调用的callable，默认值： ``None`` 。
+    - **false_fn** (callable) - 一个当 ``pred`` 是 ``False`` 时被调用的callable，默认值： ``None`` 。
+    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值： ``None`` 。
+
+返回：
+    如果 ``pred`` 是 ``True`` ，该API返回 ``true_fn()`` ，否则返回 ``false_fn()`` 。
+
+返回类型：Variable|list(Variable)|tuple(Variable)
+
+抛出异常：
+    - ``TypeError`` - 如果 ``true_fn`` 或 ``false_fn`` 不是callable。
+    - ``ValueError`` - 如果 ``true_fn`` 和 ``false_fn`` 没有返回同样的嵌套结构（nest structure），对嵌套结构的解释见上文。
+
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    import paddle.fluid.layers as layers
+    from paddle.fluid.executor import Executor
+    from paddle.fluid.framework import Program, program_guard
+
+    #
+    # pseudocode:
+    # if 0.1 < 0.23:
+    #     return 1, True
+    # else:
+    #     return 3, 2
+    #
+
+    def true_func():
+        return layers.fill_constant(
+            shape=[1, 2], dtype='int32', value=1), layers.fill_constant(
+                shape=[2, 3], dtype='bool', value=True)
+
+    def false_func():
+        return layers.fill_constant(
+            shape=[3, 4], dtype='float32', value=3), layers.fill_constant(
+                shape=[4, 5], dtype='int64', value=2)
+
+    main_program = Program()
+    startup_program = Program()
+    with program_guard(main_program, startup_program):
+        x = layers.fill_constant(shape=[1], dtype='float32', value=0.1)
+        y = layers.fill_constant(shape=[1], dtype='float32', value=0.23)
+        pred = layers.less_than(x, y)            
+        out = layers.cond(pred, true_func, false_func)
+        # out is a tuple containing 2 tensors
+
+        place = fluid.CUDAPlace(0) if fluid.core.is_compiled_with_cuda(
+        ) else fluid.CPUPlace()
+        exe = fluid.Executor(place)
+        ret = exe.run(main_program, fetch_list=out)
+        # ret[0] = [[1 1]]
+        # ret[1] = [[ True  True  True]
+        #           [ True  True  True]]
+
-- 
GitLab