Created by: shanyi15

API Guide写前须知

背景

API Guide可以理解为是API的使用指南，旨在向用户说明API的设计思路、使用方法等 撰写计划共计约45篇。其中在PaddlePaddle v1.1中，已上线14篇，例如官网-API-API使用指南-卷积

任务说明

一篇完整的API Guide，需要包含以下几个内容：

1）对本篇主题的简介，例如：

卷积有两组输入：特征图和卷积核，依据输入特征和卷积核的形状、Layout不同、计算方式的不同，在Fluid里，有针对变长序列特征的一维卷积，有针对定长图像特征的二维(2D Conv)、三维卷积(3D Conv)，同时也有卷积计算的逆向过程，下面先介绍Fluid里的2D/3D卷积，再来介绍序列卷积。

2）对主题下每个API的介绍，例如

这个layer以一个mini batch的序列为输入，在每个序列内做softmax操作。其输出为一个mini batch相同shape的序列，但在序列内是经softmax归一化过的。 这个layer往往用于在每个sequence内做softmax归一化。 API Reference 请参考 sequence_softmax

• 完整例子： 1.1已上线的API Guide

• 文档题目：请见标题

• 语言：汉语

• 格式：rst格式（因官网对rst格式支持较好，推荐用rst格式，如不了解rst，请在这里学习）

• 字数：不限

• 效果预览：

为提高Review效率，请先在本地预览，确认格式正确再提交pr，请将预览效果截图贴在pr中，不预览的pr不能合入 预览工具的使用方法请见这里

请注意：FluidDoc Repo的文档是通过Sphinx工具显示在官网上的。在Sphinx中，通过名为index.rst（或index_cn.rst等类似名称）的文件中的toctree来决定每一级显示哪几篇文档，在预览时，为了让文档能够正确预览，需要修改index，例如，如果新增一篇layers的API Guide，则需要修改doc/fluid/api/api_guides/low_level/layers/index.rst 这里的文件，并将自己文档的名字加入到index，如下图：

但在提交pr前，请不要git add 对index的修改，以避免多人同时修改这个文件引发conflict

• 提交分支：develop

• 提交位置：提交位置在FluidDoc/doc/fluid/api/api_guides/low_level

注： layers文档，请提交到FluidDoc/doc/fluid/api/api_guides/low_level/layers 多机文档，请提交到FluidDoc/doc/fluid/api/api_guides/low_level/cluster

• pr提交截止日期：请见标题

• merge截止时间：请见标题

• 需要特别注意的格式问题

在一篇API Guide中，需要给出链接跳转至API Reference，例如：

请注意：这里的超链接是用内链写成的，这样做的好处是，当某个API Reference的位置发生变化时，无需专门在文档里改超链接的路径，依然可以正确跳转。

用内链引用API Reference的方法： 以 :ref:<api_name> 的格式引用reference（而不是其他格式：例如超链接、xxx等），api_name需与对应rst文件中的名字一致。

参考示例：https://raw.githubusercontent.com/PaddlePaddle/FluidDoc/develop_doc/doc/fluid/api_guides/low_level/optimizer/optimizer_all.rst

提交pr时的注意事项

• 贴预览效果

您可以选择以下两种方式展示预览效果：贴图或者给出预览网址，以方便我们检查格式

• 检查提交了几个文件

在预览工具时，需要修改index以确保文档可以显示在预览工具中，但在提交pr时，请去掉对index的修改，只提交您新写的文档，这是为了避免多人同时修改index文件引发conflict

• PR Reviewer：

为了提高Review效率，请在PR提交时增加Reviewer：一个PR的Reviewer由Peer Reviewer+ RD Reviewer+PM Reviewer组成，分别负责检查技术、格式的问题

Peer Reviewer ：1名，请找同方向的同学，例如NLP相关API请加kuke RD Reviewer：luotao1 PM Reviewer：tink2123

• PR Labels：

为了方便管理API Guide进度，请在PR提交时增加Label API Guide