Discuss how to write API document

[ranqiu92]

其他主流DL框架API文档格式见 #8834
初步拟订PaddlePaddle 文档API 格式如下

API文档模块

API文档须包含以下几个模块（排列顺序为文档撰写顺序）：

• Python API Definition

  API的代码定义。

• Python Wrapper Location

  API的Python源码链接。

• Function Description

  API的功能描述。描述该API的含义、作用或对输入所做的操作，及参考文献和对应链接（如果有），必要时给出公式，并解释公式中关键变量的含义。

• Args Description

  API参数介绍。按代码定义中的参数顺序逐个介绍，介绍内容包含数据类型、默认值（如果有）、含义等。

• Returns

  API返回值介绍。介绍返回值含义，必要时给出对应的形状。若返回值为包含多个参数的tuple，则按顺序逐个介绍各参数。

• Exceptions（如果有）

  可能抛出的异常或错误及可能的产生原因。

• Note（如果有）

  注意事项。

• Examples

  API的使用示例。

格式及示例

Python API Definition & Python Wrapper Location

• 格式：

  [Python API Name][Python Wrapper URL]

  [Python API Definition]

• 示例

  fluid.layers.fc

fc(input,
     size,
     num_flatten_dims=1,
     param_attr=None,
     bias_attr=None,
     act=None,
     name=None,
     main_program=None,
     startup_program=None)

Function Description

• 格式

  [Function Description]

  [Formula]

  [Symbols' Descriptions if necessary]

• 示例

Applies a linear or nonlinear transformation to the input data:
     Y = Act(W^T * X + b)
where X is the input value, W is the weight, b is the bias and Act is the activation function.

Args Description

• 格式

[Arg's Name][(Data Type, Default Value)][Description]

• 示例

input (Variable): The input of the layer.
num_flatten_dims (int, default 1): The column number of the input.

Returns

• 格式

[Name][Shape]

• 示例

以dynamic_lstm为例

A tuple containing:
    The hidden state of LSTM whose shape is (T X D).
    The cell state of LSTM whose shape is (T X D).

Exceptions

• 格式

[Exception Type] [Condition]

• 示例

ValueError: If the rank of the input is less than 2.

Note

• 格式

[Note]

• 示例（暂无）

Examples

• 格式

[Python Code Snipper]

• 示例

data = fluid.layers.data(name='data', shape=[1], dtype='float32')
fc = fluid.layers.fc(input=data, size=10, act="tanh")

完整示例

fluid.layers.fc

fc(input,
   size,
   num_flatten_dims=1,
   param_attr=None,
   bias_attr=None,
   act=None,
   name=None)

Applies a linear or nonlinear transformation to the input data:

     Y = Act(W^T * X + b)

where X is the input value, W is the weight, b is the bias and Act is the activation function.

Args

input (Variable): The input value, a tensor with rank at least 2.
size (int): The size of the output.
num_flatten_dims (int, default 1): The column number of the input.
param_attr (ParamAttr or Initializer, default None): The attributes of the weights of this layer.
bias_attr (ParamAttr or Initializer, default None): The attributes of the bias of this layer.
act (str, default None): Activation type of this layer.
name (str, default None): The name of this layer.

Returns

The tensor variable storing the transformation result.

Exceptions

ValueError: If the rank of the input is less than 2.

Examples

data = fluid.layers.data(name='data', shape=[1], dtype='float32')
fc = fluid.layers.fc(input=data, size=10, act="tanh")

[luotao1]

能否提一个PR，在PR中进行评论比较方便，谢谢。该文档可放在：https://github.com/PaddlePaddle/Paddle/tree/develop/doc/fluid/dev 目录下。

[ranqiu92]

好的