API Guide 第2期：Block（11月19日初稿pr，11月26日定稿merge）
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文件中的名字一致。
提交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