From b4b2ea167907cf4be77d45bca2edb4ee8bfab42c Mon Sep 17 00:00:00 2001 From: Chen Long <1300851984@qq.com> Date: Wed, 9 Jun 2021 11:55:51 +0800 Subject: [PATCH] fix api index (#3583) * fix api index * fix api index * fix api index --- docs/api/index_cn.rst | 59 +++--- docs/api/index_en.rst | 47 +++-- docs/api/paddle/Overview_cn.rst | 94 +++++----- docs/api/paddle/arange_cn.rst | 2 +- docs/api/paddle/flatten_cn.rst | 2 +- docs/api/paddle/gather_cn.rst | 3 +- .../{fluid/dygraph/base => }/grad_cn.rst | 0 .../dygraph => }/jit/declarative_cn.rst | 0 docs/api/paddle/meshgrid_cn.rst | 1 - docs/api/paddle/mod_cn.rst | 2 +- docs/api/paddle/nn/Overview_cn.rst | 14 +- .../layers => nn}/dynamic_decode_cn.rst | 2 +- .../sampled_softmax_with_cross_entropy_cn.rst | 0 .../functional}/sequence_mask_cn.rst | 0 docs/api/paddle/slice_cn.rst | 2 +- docs/api/paddle/stack_cn.rst | 3 +- docs/api/paddle/unbind_cn.rst | 3 +- .../01_quick_start_cn.rst | 41 +++-- .../10_contribution/docs_contribution.md | 172 ++++++++---------- 19 files changed, 221 insertions(+), 226 deletions(-) rename docs/api/paddle/{fluid/dygraph/base => }/grad_cn.rst (100%) rename docs/api/paddle/{fluid/dygraph => }/jit/declarative_cn.rst (100%) rename docs/api/paddle/{fluid/layers => nn}/dynamic_decode_cn.rst (99%) rename docs/api/paddle/{fluid/layers => nn/functional}/sampled_softmax_with_cross_entropy_cn.rst (100%) rename docs/api/paddle/{fluid/layers => nn/functional}/sequence_mask_cn.rst (100%) diff --git a/docs/api/index_cn.rst b/docs/api/index_cn.rst index 7e49085f08f..f10b09db83e 100644 --- a/docs/api/index_cn.rst +++ b/docs/api/index_cn.rst @@ -12,51 +12,62 @@ API 文档 | 目录 | 功能和包含的API | +===============================+=======================================================+ | paddle.\* | paddle | -| | 根目录下保留了常用API的别名，当前包括：paddle.tensor, | +| | 根目录下保留了常用API的别名，包括：paddle.tensor, | | | paddle.framework, paddle.device 目录下的所有API | +-------------------------------+-------------------------------------------------------+ -| paddle.tensor | 跟tensor操作相关的API，如：创建zeros, | +| paddle.tensor | Tensor操作相关的API，包括 创建zeros, | | | 矩阵运算matmul, 变换concat, 计算add, 查找argmax等 | +-------------------------------+-------------------------------------------------------+ -| paddle.framework | 框架通用API和动态图模式的API，例如 no_grad 、 | +| paddle.framework | 框架通用API和动态图模式的API，包括 no_grad 、 | | | save 、 load 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.device | 设备管理相关API，如 set_device, get_device 等 | +| paddle.device | 设备管理相关API，包括 set_device, get_device 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.amp | paddle自动混合精度策略，包括 auto_cast 、 | +| paddle.amp | 自动混合精度策略，包括 auto_cast 、 | | | GradScaler 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.callbacks | paddle日志回调类，包括 ModelCheckpoint 、 | +| paddle.autograd | 自动求导相关API，包括 backward、PyLayer 等。 | ++-------------------------------+-------------------------------------------------------+ +| paddle.callbacks | 日志回调类，包括 ModelCheckpoint 、 | | | ProgBarLogger 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.nn | 组网相关的API，例如 Linear 、卷积 Conv2D 、 | -| | 循环神经网络 RNN 、损失函数 CrossEntropyLoss 、 | -| | 激活函数 ReLU 等。 | +| paddle.distributed | 分布式相关基础API | +-------------------------------+-------------------------------------------------------+ -| paddle.static | 静态图下基础框架相关API，比如：Variable, Program, | -| | Executor等 | +| paddle.distributed.fleet | 分布式相关高层API | +-------------------------------+-------------------------------------------------------+ -| paddle.static.nn | 静态图下组网专用API，例如全连接层 fc 、控制流 | -| | while_loop/cond 。 | +| paddle.hub | 模型拓展相关的API，包括 list、load、help 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.onnx | paddle转换为onnx协议相关API，比如：export | +| paddle.io | 数据输入输出相关API，包括 Dataset, DataLoader 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.optimizer | 优化算法相关API，比如：SGD，Adagrad, Adam等 | +| paddle.jit | 动态图转静态图相关API，包括 to_static、 | +| | ProgramTranslator、TracedLayer 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.optimizer.lr | 学习率衰减相关API，例如 NoamDecay 、 StepDecay 、 | -| | PiecewiseDecay 等。 | +| paddle.metric | 评估指标计算相关的API，包括 Accuracy, Auc等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.metric | 评估指标计算相关的API，比如：Accuracy, Auc等。 | +| paddle.nn | 组网相关的API，包括 Linear 、卷积 Conv2D 、 | +| | 循环神经网络 RNN 、损失函数 CrossEntropyLoss 、 | +| | 激活函数 ReLU 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.io | 数据输入输出相关API，比如：Dataset, DataLoader 等。 | +| paddle.onnx | paddle转换为onnx协议相关API，包括 export 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.distributed | 分布式相关基础API | +| paddle.optimizer | 优化算法相关API，包括 SGD，Adagrad, Adam 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.distributed.fleet | 分布式相关高层API | +| paddle.optimizer.lr | 学习率衰减相关API，包括 NoamDecay 、 StepDecay 、 | +| | PiecewiseDecay 等。 | +-------------------------------+-------------------------------------------------------+ -| paddle.vision | 视觉领域API，例如数据集 Cifar10 、数据处理 ColorJitter| -| | 、常用基础网络结构 ResNet 等。 | +| paddle.regularizer | 正则化相关API，包括 L1Decay、L2Decay 等。 | ++-------------------------------+-------------------------------------------------------+ +| paddle.static | 静态图下基础框架相关API，包括 Variable, Program, | +| | Executor等 | +-------------------------------+-------------------------------------------------------+ -| paddle.text | NLP领域API，目前包括NLP领域相关的数据集， | +| paddle.static.nn | 静态图下组网专用API，包括 全连接层 fc 、控制流 | +| | while_loop/cond 。 | ++-------------------------------+-------------------------------------------------------+ +| paddle.text | NLP领域API，包括NLP领域相关的数据集， | | | 如 Imdb 、 Movielens 。 | +-------------------------------+-------------------------------------------------------+ +| paddle.utils | 工具类相关API，包括 CppExtension、CUDAExtension 等。 | ++-------------------------------+-------------------------------------------------------+ +| paddle.vision | 视觉领域API，包括 数据集 Cifar10 、数据处理 | +| | ColorJitter、常用基础网络结构 ResNet 等。 | ++-------------------------------+-------------------------------------------------------+ diff --git a/docs/api/index_en.rst b/docs/api/index_en.rst index 33503493596..f61a65a0bcc 100644 --- a/docs/api/index_en.rst +++ b/docs/api/index_en.rst @@ -29,21 +29,28 @@ In this version, PaddlePaddle has made many optimizations to the APIs. You can r | paddle.amp | Paddle automatic mixed precision strategy, including | | | auto_cast, GradScaler, etc. | +-------------------------------+-------------------------------------------------------+ +| paddle.autograd | Auto grad API, including backward, PyLayer, etc. | ++-------------------------------+-------------------------------------------------------+ | paddle.callbacks | Paddle log callback APIs, including ModelCheckpoint, | | | ProgBarLogger, etc. | +-------------------------------+-------------------------------------------------------+ -| paddle.nn | Networking-related APIs such as Linear, Conv2D, | -| | CrossEntropyLoss, RNN，and ReLU | +| paddle.distributed | Distributed related basic APIs. | +-------------------------------+-------------------------------------------------------+ -| paddle.static | Basic framework related APIs under static graph, | -| | such as Variable, Program, Executor, etc. | +| paddle.distributed.fleet | Distributed related high-level APIs. | +-------------------------------+-------------------------------------------------------+ -| paddle.static.nn | Special APIs for networking under static graph such | -| | as full connect layer fc and control flow | -| | while_loop/cond | +| paddle.hub | Model extension API, including list, load, help, etc. | +-------------------------------+-------------------------------------------------------+ -| paddle.framework | Universal APIs and imprerative mode APIs such as | -| | to_variable and prepare_context | +| paddle.io | APIs related to data input and output such as | +| | Dataset, and DataLoader | ++-------------------------------+-------------------------------------------------------+ +| paddle.jit | Dynamic graph to static graph APIs, including | +| | to_static, ProgramTranslator, TracedLayer, etc. | ++-------------------------------+-------------------------------------------------------+ +| paddle.metric | APIs related to evaluation computation such as | +| | Accuracy and Auc. | ++-------------------------------+-------------------------------------------------------+ +| paddle.nn | Networking-related APIs such as Linear, Conv2D, | +| | CrossEntropyLoss, RNN，and ReLU, etc. | +-------------------------------+-------------------------------------------------------+ | paddle.onnx | APIs related to convert paddle model to ONNX，such as | | | export | @@ -54,22 +61,22 @@ In this version, PaddlePaddle has made many optimizations to the APIs. You can r | paddle.optimizer.lr | APIs related to learning rate decay, such as | | | NoamDecay, StepDecay, PiecewiseDecay, etc. | +-------------------------------+-------------------------------------------------------+ -| paddle.metric | APIs related to evaluation computation such as | -| | Accuracy and Auc | +| paddle.regularizer | Regularization APIs, including L1Decay, L2Decay, etc. | +-------------------------------+-------------------------------------------------------+ -| paddle.io | APIs related to data input and output such as | -| | Dataset, and DataLoader | +| paddle.static | Basic framework related APIs under static graph, | +| | such as Variable, Program, Executor, etc. | ++-------------------------------+-------------------------------------------------------+ +| paddle.static.nn | Special APIs for networking under static graph such | +| | as full connect layer fc and control flow | +| | while_loop/cond | +-------------------------------+-------------------------------------------------------+ -| paddle.distributed | Distributed related basic APIs | -| | | +| paddle.text | The NLP domain API currently includes data sets | +| | related to the NLP domain, such as Imdb and Movielens.| +-------------------------------+-------------------------------------------------------+ -| paddle.distributed.fleet | Distributed related high-level APIs | -| | | +| paddle.utils | Utils APIs, including CppExtension, CUDAExtension. | +-------------------------------+-------------------------------------------------------+ | paddle.vision | Vision domain APIs such as datasets Cifar10, | | | data processing ColorJitter, and commonly used models | | | like resnet | +-------------------------------+-------------------------------------------------------+ -| paddle.text | The NLP domain API currently includes data sets | -| | related to the NLP domain, such as Imdb and Movielens.| -+-------------------------------+-------------------------------------------------------+ + diff --git a/docs/api/paddle/Overview_cn.rst b/docs/api/paddle/Overview_cn.rst index fd4bdc5d962..3cd8c750b09 100644 --- a/docs/api/paddle/Overview_cn.rst +++ b/docs/api/paddle/Overview_cn.rst @@ -41,25 +41,25 @@ tensor数学操作 " :ref:`paddle.asin ` ", "arcsine函数" " :ref:`paddle.atan ` ", "arctangent函数" " :ref:`paddle.ceil ` ", "向上取整运算函数" - " :ref:`paddle.clip ` ", "将输入的所有元素进行剪裁，使得输出元素限制在[min, max]内" + " :ref:`paddle.clip ` ", "将输入的所有元素进行剪裁，使得输出元素限制在[min, max]内" " :ref:`paddle.conj ` ", "逐元素计算Tensor的共轭运算" " :ref:`paddle.cos ` ", "余弦函数" " :ref:`paddle.cosh ` ", "双曲余弦函数" - " :ref:`paddle.cumsum ` ", "沿给定 axis 计算张量 x 的累加和" + " :ref:`paddle.cumsum ` ", "沿给定 axis 计算张量 x 的累加和" " :ref:`paddle.divide ` ", "逐元素相除算子" - " :ref:`paddle.equal ` ", "该OP返回 x==y 逐元素比较x和y是否相等，相同位置的元素相同则返回True，否则返回False" + " :ref:`paddle.equal ` ", "该OP返回 x==y 逐元素比较x和y是否相等，相同位置的元素相同则返回True，否则返回False" " :ref:`paddle.equal_all ` ", "如果所有相同位置的元素相同返回True，否则返回False" " :ref:`paddle.erf ` ", "逐元素计算 Erf 激活函数" " :ref:`paddle.exp ` ", "逐元素进行以自然数e为底指数运算" " :ref:`paddle.floor ` ", "向下取整函数" " :ref:`paddle.floor_divide ` ", "逐元素整除算子，输入 x 与输入 y 逐元素整除，并将各个位置的输出元素保存到返回结果中" - " :ref:`paddle.greater_equal ` ", "逐元素地返回 x>=y 的逻辑值" - " :ref:`paddle.greater_than ` ", "逐元素地返回 x>y 的逻辑值" - " :ref:`paddle.increment ` ", "在控制流程中用来让 x 的数值增加 value" + " :ref:`paddle.greater_equal ` ", "逐元素地返回 x>=y 的逻辑值" + " :ref:`paddle.greater_than ` ", "逐元素地返回 x>y 的逻辑值" + " :ref:`paddle.increment ` ", "在控制流程中用来让 x 的数值增加 value" " :ref:`paddle.inverse ` ", "计算方阵的逆" " :ref:`paddle.kron ` ", "计算两个张量的克罗内克积" - " :ref:`paddle.less_equal ` ", "逐元素地返回 x<=y 的逻辑值" - " :ref:`paddle.less_than ` ", "逐元素地返回 x` ", "逐元素地返回 x<=y 的逻辑值" + " :ref:`paddle.less_than ` ", "逐元素地返回 x` ", "Log激活函数（计算自然对数）" " :ref:`paddle.log10 ` ", "Log10激活函数（计算底为10的对数）" " :ref:`paddle.log2 ` ", "计算Log1p（加一的自然对数）结果" @@ -70,22 +70,22 @@ tensor数学操作 " :ref:`paddle.logsumexp ` ", "沿着 axis 计算 x 的以e为底的指数的和的自然对数" " :ref:`paddle.max ` ", "对指定维度上的Tensor元素求最大值运算" " :ref:`paddle.maximum ` ", "逐元素对比输入的两个Tensor，并且把各个位置更大的元素保存到返回结果中" - " :ref:`paddle.mean ` ", "沿 axis 计算 x 的平均值" + " :ref:`paddle.mean ` ", "沿 axis 计算 x 的平均值" " :ref:`paddle.median ` ", "沿给定的轴 axis 计算 x 中元素的中位数" " :ref:`paddle.min ` ", "对指定维度上的Tensor元素求最小值运算" " :ref:`paddle.minimum ` ", "逐元素对比输入的两个Tensor，并且把各个位置更小的元素保存到返回结果中" " :ref:`paddle.mm ` ", "用于两个输入矩阵的相乘" - " :ref:`paddle.mod ` ", "逐元素取模算子" + " :ref:`paddle.mod ` ", "逐元素取模算子" " :ref:`paddle.multiplex ` ", "从每个输入Tensor中选择特定行构造输出Tensor" " :ref:`paddle.multiply ` ", "逐元素相乘算子" - " :ref:`paddle.not_equal ` ", "逐元素地返回x!=y 的逻辑值" - " :ref:`paddle.pow ` ", "指数算子，逐元素计算 x 的 y 次幂" + " :ref:`paddle.not_equal ` ", "逐元素地返回x!=y 的逻辑值" + " :ref:`paddle.pow ` ", "指数算子，逐元素计算 x 的 y 次幂" " :ref:`paddle.prod ` ", "对指定维度上的Tensor元素进行求乘积运算" " :ref:`paddle.reciprocal ` ", "对输入Tensor取倒数" - " :ref:`paddle.round ` ", "将输入中的数值四舍五入到最接近的整数数值" + " :ref:`paddle.round ` ", "将输入中的数值四舍五入到最接近的整数数值" " :ref:`paddle.rsqrt ` ", "rsqrt激活函数" " :ref:`paddle.scale ` ", "缩放算子" - " :ref:`paddle.sign ` ", "对输入x中每个元素进行正负判断" + " :ref:`paddle.sign ` ", "对输入x中每个元素进行正负判断" " :ref:`paddle.sin ` ", "计算输入的正弦值" " :ref:`paddle.sinh ` ", "双曲正弦函数" " :ref:`paddle.sqrt ` ", "计算输入的算数平方根" @@ -93,9 +93,9 @@ tensor数学操作 " :ref:`paddle.stanh ` ", "stanh 激活函数" " :ref:`paddle.std ` ", "沿给定的轴 axis 计算 x 中元素的标准差" " :ref:`paddle.subtract ` ", "逐元素相减算子" - " :ref:`paddle.sum ` ", "对指定维度上的Tensor元素进行求和运算" + " :ref:`paddle.sum ` ", "对指定维度上的Tensor元素进行求和运算" " :ref:`paddle.tan ` ", "三角函数tangent" - " :ref:`paddle.tanh ` ", "tanh激活函数" + " :ref:`paddle.tanh ` ", "tanh激活函数" " :ref:`paddle.trace ` ", "计算输入 Tensor 在指定平面上的对角线元素之和" " :ref:`paddle.var ` ", "沿给定的轴 axis 计算 x 中元素的方差" @@ -110,7 +110,7 @@ tensor逻辑操作 " :ref:`paddle.is_empty ` ", "测试变量是否为空" " :ref:`paddle.is_tensor ` ", "用来测试输入对象是否是paddle.Tensor" - " :ref:`paddle.isfinite ` ", "返回输入tensor的每一个值是否为Finite（既非 +/-INF 也非 +/-NaN ）" + " :ref:`paddle.isfinite ` ", "返回输入tensor的每一个值是否为Finite（既非 +/-INF 也非 +/-NaN ）" " :ref:`paddle.isinf ` ", "返回输入tensor的每一个值是否为 +/-INF" " :ref:`paddle.isnan ` ", "返回输入tensor的每一个值是否为 +/-NaN" @@ -136,22 +136,22 @@ tensor创建相关 :header: "API名称", "API功能" :widths: 10, 30 - " :ref:`paddle.arange ` ", "返回以步长 step 均匀分隔给定数值区间[start, end)的1-D Tensor，数据类型为 dtype" - " :ref:`paddle.diag ` ", "如果 x 是向量（1-D张量），则返回带有 x 元素作为对角线的2-D方阵;如果 x 是矩阵（2-D张量），则提取 x 的对角线元素，以1-D张量返回。" + " :ref:`paddle.arange ` ", "返回以步长 step 均匀分隔给定数值区间[start, end)的1-D Tensor，数据类型为 dtype" + " :ref:`paddle.diag ` ", "如果 x 是向量（1-D张量），则返回带有 x 元素作为对角线的2-D方阵;如果 x 是矩阵（2-D张量），则提取 x 的对角线元素，以1-D张量返回。" " :ref:`paddle.empty ` ", "创建形状大小为shape并且数据类型为dtype的Tensor" " :ref:`paddle.empty_like ` ", "根据 x 的shape和数据类型 dtype 创建未初始化的Tensor" - " :ref:`paddle.eye ` ", "构建二维Tensor(主对角线元素为1，其他元素为0)" + " :ref:`paddle.eye ` ", "构建二维Tensor(主对角线元素为1，其他元素为0)" " :ref:`paddle.full ` ", "创建形状大小为 shape 并且数据类型为 dtype 的Tensor" " :ref:`paddle.full_like ` ", "创建一个和 x 具有相同的形状并且数据类型为 dtype 的Tensor" " :ref:`paddle.linspace ` ", "返回一个Tensor，Tensor的值为在区间start和stop上均匀间隔的num个值，输出Tensor的长度为num" - " :ref:`paddle.meshgrid <>` ", "对每个张量做扩充操作" + " :ref:`paddle.meshgrid ` ", "对每个张量做扩充操作" " :ref:`paddle.numel ` ", "返回一个长度为1并且元素值为输入 x 元素个数的Tensor" - " :ref:`paddle.ones ` ", "创建形状为 shape 、数据类型为 dtype 且值全为1的Tensor" - " :ref:`paddle.ones_like ` ", "返回一个和 x 具有相同形状的数值都为1的Tensor" - " :ref:`paddle.Tensor ` ", "Paddle中最为基础的数据结构" + " :ref:`paddle.ones ` ", "创建形状为 shape 、数据类型为 dtype 且值全为1的Tensor" + " :ref:`paddle.ones_like ` ", "返回一个和 x 具有相同形状的数值都为1的Tensor" + " :ref:`paddle.Tensor ` ", "Paddle中最为基础的数据结构" " :ref:`paddle.to_tensor ` ", "通过已知的data来创建一个tensor" - " :ref:`paddle.zeros ` ", "该OP创建形状为 shape 、数据类型为 dtype 且值全为0的Tensor" - " :ref:`paddle.zeros_like ` ", "该OP返回一个和 x 具有相同的形状的全零Tensor，数据类型为 dtype 或者和 x 相同" + " :ref:`paddle.zeros ` ", "该OP创建形状为 shape 、数据类型为 dtype 且值全为0的Tensor" + " :ref:`paddle.zeros_like ` ", "该OP返回一个和 x 具有相同的形状的全零Tensor，数据类型为 dtype 或者和 x 相同" .. _tensor_search: @@ -162,16 +162,16 @@ tensor元素查找相关 :header: "API名称", "API功能" :widths: 10, 30 - " :ref:`paddle.argmax ` ", "沿 axis 计算输入 x 的最大元素的索引" - " :ref:`paddle.argmin ` ", "沿 axis 计算输入 x 的最小元素的索引" - " :ref:`paddle.argsort ` ", "对输入变量沿给定轴进行排序，输出排序好的数据的相应索引，其维度和输入相同" + " :ref:`paddle.argmax ` ", "沿 axis 计算输入 x 的最大元素的索引" + " :ref:`paddle.argmin ` ", "沿 axis 计算输入 x 的最小元素的索引" + " :ref:`paddle.argsort ` ", "对输入变量沿给定轴进行排序，输出排序好的数据的相应索引，其维度和输入相同" " :ref:`paddle.index_sample ` ", "对输入 x 中的元素进行批量抽样" " :ref:`paddle.index_select ` ", "沿着指定轴 axis 对输入 x 进行索引" " :ref:`paddle.masked_select ` ", "返回一个1-D 的Tensor, Tensor的值是根据 mask 对输入 x 进行选择的" " :ref:`paddle.nonzero ` ", "返回输入 x 中非零元素的坐标" " :ref:`paddle.sort ` ", "对输入变量沿给定轴进行排序，输出排序好的数据，其维度和输入相同" - " :ref:`paddle.topk ` ", "沿着可选的 axis 查找topk最大或者最小的结果和结果所在的索引信息" - " :ref:`paddle.where ` ", "该OP返回一个根据输入 condition, 选择 x 或 y 的元素组成的多维 Tensor" + " :ref:`paddle.topk ` ", "沿着可选的 axis 查找topk最大或者最小的结果和结果所在的索引信息" + " :ref:`paddle.where ` ", "该OP返回一个根据输入 condition, 选择 x 或 y 的元素组成的多维 Tensor" .. _tensor_initializer: @@ -182,7 +182,7 @@ tensor初始化相关 :header: "API名称", "API功能" :widths: 10, 30 - " :ref:`paddle.assign ` ", "将输入Tensor或numpy数组拷贝至输出Tensor" + " :ref:`paddle.assign ` ", "将输入Tensor或numpy数组拷贝至输出Tensor" .. _tensor_random: @@ -218,7 +218,7 @@ tensor线性代数相关 " :ref:`paddle.dist ` ", "计算 (x-y) 的 p 范数（p-norm）" " :ref:`paddle.dot ` ", "计算向量的内积" " :ref:`paddle.histogram ` ", "计算输入张量的直方图" - " :ref:`paddle.matmul ` ", "计算两个Tensor的乘积，遵循完整的广播规则" + " :ref:`paddle.matmul ` ", "计算两个Tensor的乘积，遵循完整的广播规则" " :ref:`paddle.mv ` ", "计算矩阵 x 和向量 vec 的乘积" " :ref:`paddle.norm ` ", "计算给定Tensor的矩阵范数（Frobenius 范数）和向量范数（向量1范数、2范数、或者通常的p范数）" " :ref:`paddle.rank ` ", "计算输入Tensor的维度（秩）" @@ -238,29 +238,29 @@ tensor元素操作相关（如：转置，reshape等） " :ref:`paddle.broadcast_to ` ", "根据 shape 指定的形状广播 x ，广播后， x 的形状和 shape 指定的形状一致" " :ref:`paddle.cast ` ", "将输入的x的数据类型转换为 dtype 并输出" " :ref:`paddle.chunk ` ", "将输入Tensor分割成多个子Tensor" - " :ref:`paddle.concat ` ", "对输入沿 axis 轴进行联结，返回一个新的Tensor" - " :ref:`paddle.expand ` ", "根据 shape 指定的形状扩展 x ，扩展后， x 的形状和 shape 指定的形状一致" - " :ref:`paddle.expand_as ` ", "根据 y 的形状扩展 x ，扩展后， x 的形状和 y 的形状相同" - " :ref:`paddle.flatten ` ", "根据给定的start_axis 和 stop_axis 将连续的维度展平" + " :ref:`paddle.concat ` ", "对输入沿 axis 轴进行联结，返回一个新的Tensor" + " :ref:`paddle.expand ` ", "根据 shape 指定的形状扩展 x ，扩展后， x 的形状和 shape 指定的形状一致" + " :ref:`paddle.expand_as ` ", "根据 y 的形状扩展 x ，扩展后， x 的形状和 y 的形状相同" + " :ref:`paddle.flatten ` ", "根据给定的start_axis 和 stop_axis 将连续的维度展平" " :ref:`paddle.flip ` ", "沿指定轴反转n维tensor" - " :ref:`paddle.gather ` ", "根据索引 index 获取输入 x 的指定 aixs 维度的条目，并将它们拼接在一起" - " :ref:`paddle.gather_nd ` ", "paddle.gather的高维推广" + " :ref:`paddle.gather ` ", "根据索引 index 获取输入 x 的指定 aixs 维度的条目，并将它们拼接在一起" + " :ref:`paddle.gather_nd ` ", "paddle.gather的高维推广" " :ref:`paddle.reshape ` ", "在保持输入 x 数据不变的情况下，改变 x 的形状" " :ref:`paddle.roll ` ", "沿着指定维度 axis 对输入 x 进行循环滚动，当元素移动到最后位置时，会从第一个位置重新插入" " :ref:`paddle.scatter ` ", "通过基于 updates 来更新选定索引 index 上的输入来获得输出" " :ref:`paddle.scatter_nd ` ", "根据 index ，将 updates 添加到一个新的张量中，从而得到输出的Tensor" " :ref:`paddle.scatter_nd_add ` ", "通过对Tensor中的单个值或切片应用稀疏加法，从而得到输出的Tensor" " :ref:`paddle.shard_index ` ", "根据分片（shard）的偏移量重新计算分片的索引" - " :ref:`paddle.slice ` ", "沿多个轴生成 input 的切片" + " :ref:`paddle.slice ` ", "沿多个轴生成 input 的切片" " :ref:`paddle.split ` ", "将输入Tensor分割成多个子Tensor" - " :ref:`paddle.squeeze ` ", "删除输入Tensor的Shape中尺寸为1的维度" - " :ref:`paddle.stack ` ", "沿 axis 轴对输入 x 进行堆叠操作" - " :ref:`paddle.strided_slice ` ", "沿多个轴生成 x 的切片" - " :ref:`paddle.tile ` ", "根据参数 repeat_times 对输入 x 的各维度进行复制" + " :ref:`paddle.squeeze ` ", "删除输入Tensor的Shape中尺寸为1的维度" + " :ref:`paddle.stack ` ", "沿 axis 轴对输入 x 进行堆叠操作" + " :ref:`paddle.strided_slice ` ", "沿多个轴生成 x 的切片" + " :ref:`paddle.tile ` ", "根据参数 repeat_times 对输入 x 的各维度进行复制" " :ref:`paddle.transpose ` ", "根据perm对输入的多维Tensor进行数据重排" - " :ref:`paddle.unbind ` ", "将输入Tensor按照指定的维度分割成多个子Tensor" - " :ref:`paddle.unique ` ", "返回Tensor按升序排序后的独有元素" - " :ref:`paddle.unsqueeze ` ", "该OP向输入Tensor的Shape中一个或多个位置（axis）插入尺寸为1的维度" + " :ref:`paddle.unbind ` ", "将输入Tensor按照指定的维度分割成多个子Tensor" + " :ref:`paddle.unique ` ", "返回Tensor按升序排序后的独有元素" + " :ref:`paddle.unsqueeze ` ", "该OP向输入Tensor的Shape中一个或多个位置（axis）插入尺寸为1的维度" " :ref:`paddle.unstack ` ", "该OP将单个dim为 D 的Tensor沿 axis 轴unpack为 num 个dim为 (D-1) 的Tensor" .. _about_framework: diff --git a/docs/api/paddle/arange_cn.rst b/docs/api/paddle/arange_cn.rst index 4f6ca1c2ff6..47a80722b87 100644 --- a/docs/api/paddle/arange_cn.rst +++ b/docs/api/paddle/arange_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_paddle_tensor_arange +.. _cn_api_paddle_tensor_arange: arange ------------------------------- diff --git a/docs/api/paddle/flatten_cn.rst b/docs/api/paddle/flatten_cn.rst index fdba816368e..cf42c3c5ae1 100644 --- a/docs/api/paddle/flatten_cn.rst +++ b/docs/api/paddle/flatten_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_fluid_layers_flatten: +.. _cn_api_paddle_flatten: flatten ------------------------------- diff --git a/docs/api/paddle/gather_cn.rst b/docs/api/paddle/gather_cn.rst index 6e40ba6bd62..63db5833326 100644 --- a/docs/api/paddle/gather_cn.rst +++ b/docs/api/paddle/gather_cn.rst @@ -1,4 +1,5 @@ -.. _cn_api_paddle_tensor_gather +.. _cn_api_paddle_tensor_gather: + gather ------------------------------- diff --git a/docs/api/paddle/fluid/dygraph/base/grad_cn.rst b/docs/api/paddle/grad_cn.rst similarity index 100% rename from docs/api/paddle/fluid/dygraph/base/grad_cn.rst rename to docs/api/paddle/grad_cn.rst diff --git a/docs/api/paddle/fluid/dygraph/jit/declarative_cn.rst b/docs/api/paddle/jit/declarative_cn.rst similarity index 100% rename from docs/api/paddle/fluid/dygraph/jit/declarative_cn.rst rename to docs/api/paddle/jit/declarative_cn.rst diff --git a/docs/api/paddle/meshgrid_cn.rst b/docs/api/paddle/meshgrid_cn.rst index fcc9a685a0d..380387f5cfe 100644 --- a/docs/api/paddle/meshgrid_cn.rst +++ b/docs/api/paddle/meshgrid_cn.rst @@ -1,4 +1,3 @@ - .. _cn_api_paddle_tensor_meshgrid: meshgrid diff --git a/docs/api/paddle/mod_cn.rst b/docs/api/paddle/mod_cn.rst index 3781463819a..ab24104c19d 100644 --- a/docs/api/paddle/mod_cn.rst +++ b/docs/api/paddle/mod_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_tensor_remainder: +.. _cn_api_tensor_mod: mod ------------------------------- diff --git a/docs/api/paddle/nn/Overview_cn.rst b/docs/api/paddle/nn/Overview_cn.rst index 8f52a6ae9bf..bb060268f90 100644 --- a/docs/api/paddle/nn/Overview_cn.rst +++ b/docs/api/paddle/nn/Overview_cn.rst @@ -168,7 +168,7 @@ Normalization层 " :ref:`paddle.nn.BiRNN ` ", "双向循环神经网络" " :ref:`paddle.nn.GRU ` ", "门控循环单元网络" - " :ref:`paddle.nn.GRUCell ` ", "门控循环单元" + " :ref:`paddle.nn.GRUCell ` ", "门控循环单元" " :ref:`paddle.nn.LSTM ` ", "长短期记忆网络" " :ref:`paddle.nn.LSTMCell ` ", "长短期记忆网络单元" " :ref:`paddle.nn.RNN ` ", "循环神经网络" @@ -288,7 +288,7 @@ Clip相关 " :ref:`paddle.nn.BeamSearchDecoder ` ", "带beam search解码策略的解码器" " :ref:`paddle.nn.CosineSimilarity ` ", "余弦相似度计算" - " :ref:`paddle.nn.dynamic_decode ` ", "循环解码" + " :ref:`paddle.nn.dynamic_decode ` ", "循环解码" " :ref:`paddle.nn.Flatten ` ", "将一个连续维度的Tensor展平成一维Tensor" " :ref:`paddle.nn.PairwiseDistance ` ", "计算两个向量之间pairwise的距离" @@ -400,7 +400,6 @@ Normalization方法 " :ref:`paddle.nn.functional.bilinear ` ", "对两个输入执行双线性张量积" " :ref:`paddle.nn.functional.linear ` ", "线性变换" - " :ref:`paddle.nn.functional.linear_lr_warmup ` ", "线性学习率热身(warm up)" .. _dropout_functional: @@ -453,7 +452,6 @@ Embedding相关函数 " :ref:`paddle.nn.functional.sigmoid_focal_loss ` ", "用于计算分类任务中前景类-背景类数量不均衡问题的损失" " :ref:`paddle.nn.functional.smooth_l1_loss ` ", "用于计算平滑L1损失" " :ref:`paddle.nn.functional.softmax_with_cross_entropy ` ", "将softmax操作、交叉熵损失函数的计算过程进行合并" - " :ref:`paddle.nn.functional.ssd_loss ` ", "用于SSD物体检测算法的多窗口损失计算" .. _common_functional: @@ -464,21 +462,13 @@ Embedding相关函数 :header: "API名称", "API功能" - " :ref:`paddle.nn.functional.add_position_encoding ` ", "将输入inpu中每个位置（序列中的位置）的特征与对应的位置编码加权求和" - " :ref:`paddle.nn.functional.affine_channel ` ", "对输入的每个 channel 应用单独的仿射变换" " :ref:`paddle.nn.functional.affine_grid ` ", "用于生成仿射变换前后的feature maps的坐标映射关系" - " :ref:`paddle.nn.functional.assign ` ", "将输入Tensor或numpy数组拷贝至输出Tensor" " :ref:`paddle.nn.functional.cosine_similarity ` ", "用于计算x1与x2沿axis维度的余弦相似度" " :ref:`paddle.nn.functional.cross_entropy ` ", "计算输入input和标签label间的交叉熵" - " :ref:`paddle.nn.functional.detection_output ` ", "给定回归位置偏移、置信度以及先验框信息计算检测的输出" - " :ref:`paddle.nn.functional.distribute_fpn_proposals ` ", "Feature Pyramid Networks（FPN）模型中依据proposal的尺度和参考尺度与级别将所有proposal分配到不同的FPN级别中" " :ref:`paddle.nn.functional.grid_sample ` ", "用于调整一个batch中图片的大小" - " :ref:`paddle.nn.functional.iou_similarity ` ", "计算两个框列表的intersection-over-union(IOU)" " :ref:`paddle.nn.functional.label_smooth ` ", "标签平滑" - " :ref:`paddle.nn.functional.edit_distance ` ", "计算一批给定字符串及其参照字符串间的编辑距离" " :ref:`paddle.nn.functional.one_hot ` ", "将输入'x'中的每个id转换为一个one-hot向量" " :ref:`paddle.nn.functional.pixel_shuffle ` ", "将Tensor重新排列" - " :ref:`paddle.nn.functional.space_to_depth ` ", "对成块的空间数据进行重组" " :ref:`paddle.nn.functional.square_error_cost ` ", "用于计算预测值和目标值的方差估计" " :ref:`paddle.nn.functional.unfold ` ", "对每一个卷积核覆盖下的区域，将元素重新排成一列" diff --git a/docs/api/paddle/fluid/layers/dynamic_decode_cn.rst b/docs/api/paddle/nn/dynamic_decode_cn.rst similarity index 99% rename from docs/api/paddle/fluid/layers/dynamic_decode_cn.rst rename to docs/api/paddle/nn/dynamic_decode_cn.rst index 05ee35c8456..fa54baf05ed 100644 --- a/docs/api/paddle/fluid/layers/dynamic_decode_cn.rst +++ b/docs/api/paddle/nn/dynamic_decode_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_fluid_layers_dynamic_decode: +.. _cn_api_paddle_nn_dynamic_decode: dynamic_decode ------------------------------- diff --git a/docs/api/paddle/fluid/layers/sampled_softmax_with_cross_entropy_cn.rst b/docs/api/paddle/nn/functional/sampled_softmax_with_cross_entropy_cn.rst similarity index 100% rename from docs/api/paddle/fluid/layers/sampled_softmax_with_cross_entropy_cn.rst rename to docs/api/paddle/nn/functional/sampled_softmax_with_cross_entropy_cn.rst diff --git a/docs/api/paddle/fluid/layers/sequence_mask_cn.rst b/docs/api/paddle/nn/functional/sequence_mask_cn.rst similarity index 100% rename from docs/api/paddle/fluid/layers/sequence_mask_cn.rst rename to docs/api/paddle/nn/functional/sequence_mask_cn.rst diff --git a/docs/api/paddle/slice_cn.rst b/docs/api/paddle/slice_cn.rst index 5c58d47a048..45a9bc8d8ba 100755 --- a/docs/api/paddle/slice_cn.rst +++ b/docs/api/paddle/slice_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_fluid_layers_slice: +.. _cn_api_paddle_slice: slice ------------------------------- diff --git a/docs/api/paddle/stack_cn.rst b/docs/api/paddle/stack_cn.rst index 0edcf6632a1..1d51eb6bbd8 100644 --- a/docs/api/paddle/stack_cn.rst +++ b/docs/api/paddle/stack_cn.rst @@ -1,4 +1,5 @@ -.. _cn_api_paddle_tensor_arange +.. _cn_api_paddle_tensor_stack: + stack ------------------------------- diff --git a/docs/api/paddle/unbind_cn.rst b/docs/api/paddle/unbind_cn.rst index e4b3836388f..ae21274b033 100644 --- a/docs/api/paddle/unbind_cn.rst +++ b/docs/api/paddle/unbind_cn.rst @@ -1,4 +1,5 @@ -.. _cn_api_paddle_tensor_unbind +.. _cn_api_paddle_tensor_unbind: + unbind ------------------------------- diff --git a/docs/guides/02_paddle2.0_develop/01_quick_start_cn.rst b/docs/guides/02_paddle2.0_develop/01_quick_start_cn.rst index 909e3c42171..06b8ef5daef 100644 --- a/docs/guides/02_paddle2.0_develop/01_quick_start_cn.rst +++ b/docs/guides/02_paddle2.0_develop/01_quick_start_cn.rst @@ -37,10 +37,12 @@ .. code:: ipython3 - from paddle.vision.transforms import ToTensor - - train_dataset = paddle.vision.datasets.MNIST(mode='train', transform=ToTensor()) - val_dataset = paddle.vision.datasets.MNIST(mode='test', transform=ToTensor()) + import paddle.vision.transforms as T + transform = T.Normalize(mean=[127.5], std=[127.5], data_format='CHW') + + # 下载数据集 + train_dataset = paddle.vision.datasets.MNIST(mode='train', transform=transform) + val_dataset = paddle.vision.datasets.MNIST(mode='test', transform=transform) 3.2 模型搭建 ~~~~~~~~~~~~ @@ -66,32 +68,33 @@ # 预计模型结构生成模型对象，便于进行后续的配置、训练和验证 model = paddle.Model(mnist) - + # 模型训练相关配置，准备损失计算方法，优化器和精度计算方法 model.prepare(paddle.optimizer.Adam(parameters=model.parameters()), - paddle.nn.CrossEntropyLoss(), - paddle.metric.Accuracy()) - + paddle.nn.CrossEntropyLoss(), + paddle.metric.Accuracy()) + # 开始模型训练 model.fit(train_dataset, - epochs=5, - batch_size=64, - verbose=1) + epochs=5, + batch_size=64, + verbose=1) .. parsed-literal:: - The loss value printed in the log is the current step, and the metric is the average value of previous step. + + The loss value printed in the log is the current step, and the metric is the average value of previous steps. Epoch 1/5 - step 938/938 [==============================] - loss: 0.1161 - acc: 0.9298 - 16ms/step + step 938/938 [==============================] - loss: 0.1801 - acc: 0.9032 - 8ms/step Epoch 2/5 - step 938/938 [==============================] - loss: 0.0272 - acc: 0.9691 - 15ms/step + step 938/938 [==============================] - loss: 0.0544 - acc: 0.9502 - 8ms/step Epoch 3/5 - step 938/938 [==============================] - loss: 0.0326 - acc: 0.9789 - 16ms/step + step 938/938 [==============================] - loss: 0.0069 - acc: 0.9595 - 7ms/step Epoch 4/5 - step 938/938 [==============================] - loss: 0.0043 - acc: 0.9826 - 16ms/step + step 938/938 [==============================] - loss: 0.0094 - acc: 0.9638 - 7ms/step Epoch 5/5 - step 938/938 [==============================] - loss: 0.0853 - acc: 0.9863 - 15ms/step + step 938/938 [==============================] - loss: 0.1414 - acc: 0.9670 - 8ms/step 3.4 模型评估 ~~~~~~~~~~~~ @@ -105,9 +108,9 @@ .. parsed-literal:: - {'loss': [1.0728842e-06], 'acc': 0.9822} + {'loss': [2.145765e-06], 'acc': 0.9751} -可以看出，初步训练得到的模型效果在98%附近，在逐渐了解飞桨后，你可以通过调整其中的训练参数来提升模型的精度。 +可以看出，初步训练得到的模型效果在97.5%附近，在逐渐了解飞桨后，你可以通过调整其中的训练参数来提升模型的精度。 至此你就通过飞桨几个简单的API完成了一个深度学习任务，你也可以针对自己的需求来更换其中的代码，比如对数据集进行增强、使用 ``CNN`` 模型等，飞桨官网提供了丰富的教程与案例可供参考。 diff --git a/docs/guides/10_contribution/docs_contribution.md b/docs/guides/10_contribution/docs_contribution.md index 2904d84c8e5..a658df790c8 100644 --- a/docs/guides/10_contribution/docs_contribution.md +++ b/docs/guides/10_contribution/docs_contribution.md @@ -1,23 +1,24 @@ # 中文API文档贡献指南 -PaddlePaddle 的中文API文档以 rst 文件的格式，存储于 [PaddlePaddle/FluidDoc](https://github.com/PaddlePaddle/FluidDoc) 中，通过技术手段，将rst文件转为 HTML文件后呈现至[官网API文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html) 。如果想要修改中文API文档，需要按以下流程完成修改。 +PaddlePaddle 的中文API文档以 rst 文件的格式，存储于 [PaddlePaddle/docs](https://github.com/PaddlePaddle/docs) 中，通过技术手段，将rst文件转为 HTML文件后呈现至[官网API文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html) 。如果想要修改中文API文档，需要按以下流程完成修改。 + ## 一、修改前的准备工作 ### 1.1 Fork -先跳转到 [PaddlePaddle/FluidDoc](https://github.com/PaddlePaddle/FluidDoc) GitHub 首页，然后单击 Fork 按钮，生成自己仓库下的目录，比如你的 GitHub 用户名为 USERNAME，则生成： https://github.com/USERNAME/FluidDoc。 +先跳转到 [PaddlePaddle/docs](https://github.com/PaddlePaddle/docs) GitHub 首页，然后单击 Fork 按钮，生成自己仓库下的目录，比如你的 GitHub 用户名为 USERNAME，则生成： https://github.com/USERNAME/docs。 ### 1.2 Clone 将你目录下的远程仓库clone到本地。 ``` -➜ git clone https://github.com/USERNAME/FluidDoc -➜ cd FluidDoc +➜ git clone https://github.com/USERNAME/docs +➜ cd docs ``` ### 1.3 创建本地分支 -FluidDoc 目前使用 [Git流分支模型](https://nvie.com/posts/a-successful-git-branching-model/)进行开发，测试，发行和维护。 +docs 目前使用 [Git流分支模型](https://nvie.com/posts/a-successful-git-branching-model/)进行开发，测试，发行和维护。 所有的 feature 和 bug fix 的开发工作都应该在一个新的分支上完成，一般从 develop 分支上创建新分支。 @@ -45,19 +46,18 @@ Paddle 使用 clang-format 来调整 C/C++ 源代码格式，请确保 clang-for ## 二、正式修改API文档 -目前，[FluidDoc](https://github.com/PaddlePaddle/FluidDoc) 的 `doc/paddle/api` 下存放了与 Paddle 中文API文档所有相关的文件。说明如下： +目前，[docs](https://github.com/PaddlePaddle/docs) 的 `docs/api/` 下存放了与 Paddle 中文API文档所有相关的文件。说明如下： ``` -doc/paddle/api -|--paddle # 存放中文API文档，文件名为api_name_cn.rst,路径为真实实现的路径 +docs/api +|--paddle # 存放中文API文档，文件名为api_name_cn.rst,路径为暴露的路径 | |--amp | |--compat | |--device ... | |--utils | |--vision -|-- alias_api_mapping # 定义了API别名关系，影响官网API文档展示逻辑 |-- api_label # 英文API文档的标签，用于API文档的相互引用 -|-- display_doc_list +|-- display_doc_list |-- gen_alias_api.py # 生成全量的API别名关系 |-- gen_alias_mapping.sh # 已废弃 |-- gen_doc.py # 生成英文API文档目录树程序 @@ -69,104 +69,88 @@ doc/paddle/api ### 2.1 新增 API 文档 -当你新增了一个API时，需要同时新增该API的中文文档。你需要在该API文档的真实实现路径下，新建一个 api_name_cn.rst 文件，文件内容需要按照 [飞桨API文档书写规范](https://github.com/PaddlePaddle/FluidDoc/wiki/%E9%A3%9E%E6%A1%A8API%E6%96%87%E6%A1%A3%E4%B9%A6%E5%86%99%E8%A7%84%E8%8C%83)进行书写。 - -**注意：** 真实实现路径是指，该API在 [PaddlePaddle/Paddle](https://github.com/PaddlePaddle/Paddle) 的实现路径。举例来说，对于 ``paddle.all``，其实现的路径为 ``python/paddle/tensor/math.py``，因此其真实实现的路径为 ``paddle/tensor/math``；所以，在 [PaddlePaddle/FluidDoc](https://github.com/PaddlePaddle/FluidDoc) 中，需要在 ``doc/paddle/api`` 目录下，进入``paddle/tensor/math``，然后新建 all_cn.rst 文件，按 [规范](https://github.com/PaddlePaddle/FluidDoc/wiki/%E9%A3%9E%E6%A1%A8API%E6%96%87%E6%A1%A3%E4%B9%A6%E5%86%99%E8%A7%84%E8%8C%83) 书写``paddle.all`` 的中文文档内容即可。 +当你新增了一个API时，需要同时新增该API的中文文档。你需要在该API文档的暴露路径下，新建一个 api_name_cn.rst 文件，文件内容需要按照 [飞桨API文档书写规范](https://github.com/PaddlePaddle/docs/wiki/%E9%A3%9E%E6%A1%A8API%E6%96%87%E6%A1%A3%E4%B9%A6%E5%86%99%E8%A7%84%E8%8C%83)进行书写。 -**注意：** Paddle 中存在部分特殊的API：[飞桨特殊API实现](https://github.com/PaddlePaddle/FluidDoc/wiki/%E9%A3%9E%E6%A1%A8API%E7%89%B9%E6%AE%8A%E5%AE%9E%E7%8E%B0)，其真实实现不能按如上的规则确定，可查看 [飞桨特殊API实现](https://github.com/PaddlePaddle/FluidDoc/wiki/%E9%A3%9E%E6%A1%A8API%E7%89%B9%E6%AE%8A%E5%AE%9E%E7%8E%B0) 确认其真实实现的路径。 +**注意：** 暴露路径是指，在开发API时，确认的API路径，如 `paddle.add`、`paddle.nn.Conv2D` 等。 ### 2.2 修改 API 文档 -修改中文API文档，可以通过API的URL，确定API文档的源文件。如 ``paddle.all`` 的中文API文档URL为：[https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/tensor/math/all_cn.html](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/tensor/math/all_cn.html)，URL路径中，``api/paddle/tensor/math/all_cn.html`` 即对应 ``(FluidDoc/doc/paddle/)api/paddle/tensor/math/all_cn.rst`` , 因此，可以很快的确定中文API文档的源文件，然后直接修改即可。 - -### 2.3 修改API别名关系 -Paddle 的API目前存在别名关系，如同一个API ``all`` 的调用方式有三种，分别为``paddle.all、paddle.tensor.all、paddle.tensor.math.all``；其中，由于paddle 建议使用路径较短的API，因此 ``paddle.all`` 即为 ``all`` 的推荐别名；又因为 ``all`` 的实现在 [PaddlePaddle/Paddle](https://github.com/PaddlePaddle/Paddle) 的 ``python/paddle/tensor/math.py`` 中，因此其真实实现的别名为 ``paddle.tensor.math.all``。 - -而[飞桨官网API文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html)针对每一个API，都仅在推荐别名目录下展示其API文档，如只在 ``paddle`` 目录下展示 ``all`` 的API文档，而不会在 ``paddle.tensor`` 与 ``paddle.tensor.math`` 。 - -这个逻辑的实现依赖 [alias_api_mapping](https://github.com/PaddlePaddle/FluidDoc/blob/develop/doc/paddle/api/alias_api_mapping)，这个文件定义了Paddle API 的别名关系，每一行的规则为API的 **真实实现 + '\t' + 推荐别名,别名1,别名2...** ； -如对于 ``all`` ，其别名关系为 +修改中文API文档，可以通过API的URL，确定API文档的源文件。如 ``paddle.all`` 的中文API文档URL为：https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/all_cn.html，URL路径中，``api/paddle/all_cn.html`` 即对应 ``(docs/docs/)api/paddle/all_cn.rst`` , 因此，可以很快的确定中文API文档的源文件，然后直接修改即可。 - paddle.tensor.math.all paddle.all,paddle.tensor.all - -就表明 ``all`` 这个API的真实实现为 ``paddle.tensor.math.all``，但是推荐别名为 ``paddle.all`` 。 - -**注意：** 对于一些特殊的API，具体列表见：[飞桨特殊API实现](https://github.com/PaddlePaddle/FluidDoc/wiki/%E9%A3%9E%E6%A1%A8API%E7%89%B9%E6%AE%8A%E5%AE%9E%E7%8E%B0),该列表中给出了每个API的真实实现与推荐别名。 ## 三、提交&push ### 3.1 提交&触发CI单测 -- 修改 ``paddle/tensor/math/all_cn.rst`` 这个文件，并提交这个文件 +- 修改 ``paddle/all_cn.rst`` 这个文件，并提交这个文件 - ``` - ➜ git status - On branch my-cool-stuff - Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git restore ..." to discard changes in working directory) - modified: paddle/tensor/math/all_cn.rst +``` +➜ git status +On branch my-cool-stuff +Changes not staged for commit: +(use "git add ..." to update what will be committed) +(use "git restore ..." to discard changes in working directory) +modified: paddle/all_cn.rst - no changes added to commit (use "git add" and/or "git commit -a") +no changes added to commit (use "git add" and/or "git commit -a") - ➜ git add paddle/tensor/math/all_cn.rst - ``` +➜ git add paddle/all_cn.rst +``` - **如果你不想提交本次修改**，使用 ``git checkout -- `` 取消上面对``python/paddle/tensor/math.py``文件的提交，可以将它恢复至上一次提交的状态: - ``` - ➜ git checkout -- paddle/tensor/math/all_cn.rst - ``` + **如果你不想提交本次修改**，使用 ``git checkout -- `` 取消上面对``paddle/all_cn.rst``文件的提交，可以将它恢复至上一次提交的状态: +``` +➜ git checkout -- paddle/all_cn.rst +``` 恢复后重新进行修改并提交文件即可。 - + - pre-commit：提交修改说明前，需要对本次修改做一些格式化检查： - - ``` - ➜ pre-commit - CRLF end-lines remover...............................(no files to check)Skipped - yapf.....................................................................Passed - Check for added large files..............................................Passed - Check for merge conflicts................................................Passed - Check for broken symlinks................................................Passed - Detect Private Key...................................(no files to check)Skipped - Fix End of Files.........................................................Passed - clang-format.........................................(no files to check)Skipped - cpplint..............................................(no files to check)Skipped - pylint...................................................................Passed - copyright_checker........................................................Passed - ``` + +``` +➜ pre-commit +CRLF end-lines remover...............................(no files to check)Skipped +yapf.....................................................................Passed +Check for added large files..............................................Passed +Check for merge conflicts................................................Passed +Check for broken symlinks................................................Passed +Detect Private Key...................................(no files to check)Skipped +Fix End of Files.........................................................Passed +clang-format.........................................(no files to check)Skipped +cpplint..............................................(no files to check)Skipped +pylint...................................................................Passed +copyright_checker........................................................Passed +``` 全部Passed 或 Skipped后，即可进入下一步。如果有 Failed 文件，则需要按照规范，修改出现Failed 的文件后，重新 ``git add -> pre-commit`` ，直至没有 Failed 文件。 - - ``` - ➜ pre-commit - CRLF end-lines remover...............................(no files to check)Skipped - yapf.....................................................................Failed - - hook id: yapf - - files were modified by this hook - Check for added large files..............................................Passed - Check for merge conflicts................................................Passed - Check for broken symlinks................................................Passed - Detect Private Key...................................(no files to check)Skipped - Fix End of Files.........................................................Passed - clang-format.........................................(no files to check)Skipped - cpplint..............................................(no files to check)Skipped - pylint...................................................................Failed - - hook id: pylint-doc-string - - exit code: 127 - - ./tools/codestyle/pylint_pre_commit.hook: line 11: pylint: command not found - - copyright_checker........................................................Passed - ``` +``` +➜ pre-commit +CRLF end-lines remover...............................(no files to check)Skipped +yapf.....................................................................Failed +- hook id: yapf +- files were modified by this hook +Check for added large files..............................................Passed +Check for merge conflicts................................................Passed +Check for broken symlinks................................................Passed +Detect Private Key...................................(no files to check)Skipped +Fix End of Files.........................................................Passed +clang-format.........................................(no files to check)Skipped +cpplint..............................................(no files to check)Skipped +pylint...................................................................Failed +- hook id: pylint-doc-string +- exit code: 127 + +./tools/codestyle/pylint_pre_commit.hook: line 11: pylint: command not found + +copyright_checker........................................................Passed +``` - 填写提交说明：Git 每次提交代码，都需要写提交说明，让其他人知道这次提交做了哪些改变，可以通过 ``git commit`` 完成： - ``` - ➜ git commit -m "fix all docs bugs" - ``` +``` +➜ git commit -m "fix all docs bugs" +``` ### 3.2 确保本地仓库是最新的 -在准备发起 Pull Request 之前，需要同步原仓库（https://github.com/PaddlePaddle/FluidDoc）最新的代码。 +在准备发起 Pull Request 之前，需要同步原仓库（https://github.com/PaddlePaddle/docs）最新的代码。 首先通过 ``git remote`` 查看当前远程仓库的名字。 @@ -174,14 +158,14 @@ Paddle 的API目前存在别名关系，如同一个API ``all`` 的调用方式 ➜ git remote origin ➜ git remote -v -origin https://github.com/USERNAME/FluidDoc (fetch) -origin https://github.com/USERNAME/FluidDoc (push) +origin https://github.com/USERNAME/docs (fetch) +origin https://github.com/USERNAME/docs (push) ``` 这里 origin 是你 clone 的远程仓库的名字，也就是自己用户名下的 Paddle，接下来创建一个原始 Paddle 仓库的远程主机，命名为 upstream。 ``` -➜ git remote add upstream https://github.com/PaddlePaddle/FluidDoc +➜ git remote add upstream https://github.com/PaddlePaddle/docs ➜ git remote origin upstream @@ -196,7 +180,7 @@ upstream ### 3.3 Push 到远程仓库 -将本地的修改推送到 GitHub 上，也就是 https://github.com/USERNAME/FluidDoc。 +将本地的修改推送到 GitHub 上，也就是 https://github.com/USERNAME/docs。 ``` # 推送到远程仓库 origin 的 my-cool-stuff 分支上 @@ -205,22 +189,20 @@ upstream ## 四、提交PR -在你push后在对应仓库会提醒你进行PR操作： +在你push后在对应仓库会提醒你进行PR操作，按格式填写PR内容，即可。 -点击后，按格式填写PR内容，即可。 ## 五、review&merge -提交PR后，可以点击右侧的Reviewers，指定 Paddle 的同学进行 Review。 +提交PR后，可以指定 Paddle 的同学进行 Review。 目前，Paddle 负责API文档的同学是 @TCChenLong、@jzhang533、@saxon-zh、@Heeenrrry、@dingjiaweiww等 。 -目前，Paddle 负责API文档的同学是 @TCChenLong，可以直接指定他进行文档Review；此外，你也可以指定 @jzhang533、@saxon-zh、@Heeenrrry、@swtkiwi、@dingjiaweiww等同学review 。 ## CI -Paddle 中与文档相关的CI 流水线是 `PR-CI-CPU-Py2-18`等，主要对以下几个方面进行检查: +Paddle 中与文档相关的CI 流水线是 `Docs-NEW`等，主要对以下几个方面进行检查: - 检查PR CLA - 检查增量修改的API是否需要相关人员审核 - 若需要执行示例代码则执行看能否正常运行 -如果无法通过该CI，请点击对应CI的details，查看CI运行的的log，并根据log修改你的PR，直至通过CI。 +如果无法通过该CI，请点击对应CI的details，查看CI运行的的log，并根据log修改你的PR，直至通过CI。 \ No newline at end of file