com um clique
api-docs-updater
// 负责《Paddle API 对齐 PyTorch 项目》中 Step4:API 文档修改,在 API 代码修改完成后,同步更新中文 API 文档,确保文档准确反映 API 的最新行为
// 负责《Paddle API 对齐 PyTorch 项目》中 Step4:API 文档修改,在 API 代码修改完成后,同步更新中文 API 文档,确保文档准确反映 API 的最新行为
负责《Paddle API 对齐 PyTorch 项目》中 Step1:方案决策,分析 PyTorch API 与 Paddle API 之间的差异,制定合适的 API 改动方案
开展《Paddle API 对齐 PyTorch 项目》,负责项目整体统筹规划,调用多个 skill,完成输入的 API 对齐
负责《Paddle API 对齐 PyTorch 项目》中 Step2:API 代码修改,实施 C++下沉的代码开发。通过将 Python API 下沉至 C++层,可以减少 Python 装饰器带来的性能开销,提升 API 调度效率。
负责《Paddle API 对齐 PyTorch 项目》中 Step5:代码提交,分别对 Paddle、PaConvert、Docs 三个仓库创建或更新 Pull Request
负责《Paddle API 对齐 PyTorch 项目》中 Step2:API 代码修改,实施 Python 装饰器的代码开发。通过 Python 装饰器,在 Python 层为 Paddle API 提供参数别名、参数顺序、参数类型和参数用法的兼容转换,实现 PyTorch 风格的 API 调用,并保持 Paddle API 的向后兼容性。
负责《Paddle API 对齐 PyTorch 项目》中 Step3:Pytorch 对齐验证,基于 PaConvert 工具验证 Paddle API 与 PyTorch API 是否用法完全对齐一致
| name | api-docs-updater |
| description | 负责《Paddle API 对齐 PyTorch 项目》中 Step4:API 文档修改,在 API 代码修改完成后,同步更新中文 API 文档,确保文档准确反映 API 的最新行为 |
| allowed-tools | Read Grep Glob Write Edit |
| disable-model-invocation | false |
涉及以下文档的修改:
| 文档类型 | 文件命名 | 改动点 |
|---|---|---|
| API 概览文档 | ${ROOT_DIR}/docs/api/paddle/Overview_cn.rst | API 索引目录,新增 API 时需要更新 |
| API 中文文档 | {api_name}_cn.rst | 针对 API 功能改动点,修改文档 |
Step 1. 查找 API 英文文档 - 在两个位置查找:
__doc__ 文档字符串${ROOT_DIR}/Paddle/python/paddle/_paddle_docs.py 文件中Step 2. 对比英文和中文文档 - 识别不一致之处
Step 3. 根据代码修改方案选择对应模式 - 见第三章
Step 4. 按照格式规范更新中文文档 - 见第四章
根据代码修改方案的不同,文档需要采用不同的修改模式。本章覆盖所有常见场景,并提供完整的实战示例。
适用场景:
@param_one_alias / @param_two_alias / @ParamAliasDecorator 装饰器修改内容:
英文文档要求(代码 docstring):
Alias: + 别名 Alias: input` or ` other ``Args:
x (Tensor): Input tensor. Alias: ``input``.
axis (int, optional): Axis. Alias: ``dim``.
中文文档要求(.rst 文件):
别名 + 别名 (与英文格式保持一致)别名 input` ` 或 ` other ``完整实战示例 - paddle.atan2(参数别名+out 参数)
.. py:function:: paddle.atan2(x, y, name=None, *, out=None)
参数
:::::::::
- **x** (Tensor) - 输入的 Tensor。别名 ``input``。
- **y** (Tensor) - 输入的 Tensor。别名 ``other``。
- **name** (str,可选) - 操作的名称。
关键字参数
:::::::::
- **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。
返回
:::::::::
Tensor:计算结果 Tensor。
适用场景:
修改内容:
文档要求:
完整实战示例 - paddle.broadcast_tensors
.. py:function:: paddle.broadcast_tensors(input, name=None)
此 API 有两种调用方式:
1. ``paddle.broadcast_tensors(input, name=None)`` (Paddle 风格):
接收一个 Tensor 序列作为参数
2. ``paddle.broadcast_tensors(*tensors)`` (PyTorch 风格):
接收可变个 Tensor 参数
参数
:::::::::
- **input** (Sequence[Tensor]) - 待广播的 Tensor 序列。别名 ``*tensors``。
- **name** (str,可选) - 操作名称。
返回
:::::::::
list[Tensor]:广播后的 Tensor 列表。
适用场景:
修改内容:
, *, out=None(keyword-only)或 , out=None(位置参数)英文文档要求(代码 docstring):
keyword-only 形式:
Keyword Args:
out (Tensor|None, optional): The output Tensor. Default: None.
位置参数形式:
Args:
...
out (Tensor|None, optional): The output Tensor. Default: None.
中文文档要求(.rst 文件):
keyword-only 形式:
.. py:function:: paddle.api(x, name=None, *, out=None)
参数
:::::
- **x** (Tensor) - 输入 Tensor。
- **name** (str,可选) - 操作名称。
关键字参数
::::::::::
- **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。
位置参数形式:
.. py:function:: paddle.api(x, out=None, name=None)
参数
:::::
- **x** (Tensor) - 输入 Tensor。
- **out** (Tensor,可选) - 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。
- **name** (str,可选) - 操作名称。
适用场景:
frexp 返回 mantissa 和 exponent)修改内容:
, *, out=Nonetuple[Tensor, Tensor]完整实战示例 - paddle.frexp
.. py:function:: paddle.frexp(x, name=None, *, out=None)
用于把一个浮点数分解为尾数和指数的函数,返回一个尾数 Tensor 和一个指数 Tensor。
参数
:::::::::
- **x** (Tensor) - 输入是一个多维的 Tensor,数据类型为 float32、float64。别名 ``input``。
- **name** (str,可选) - 具体用法请参见 :ref:`api_guide_Name`,默认值为 None。
关键字参数
::::::::::
- **out** (tuple[Tensor, Tensor],可选) - 输出 Tensor 元组,若不为 ``None``,计算结果将保存在该 Tensor 元组中,默认值为 ``None``。
返回
:::::::::
mantissa(Tensor):分解后的尾数,形状和原输入一致。
exponent(Tensor):分解后的指数,形状和原输入一致。
适用场景:
_ 结尾,如 paddle.abs_、paddle.floor_divide_)修改内容:
.. note:: 块描述别名中文文档要求(.rst 文件):
.. py:function:: paddle.floor_divide_(x, y, name=None)
Inplace 版本的 :ref:`cn_api_paddle_floor_divide` API,对输入 `x` 采用 Inplace 策略。
更多关于 inplace 操作的介绍请参考 `3.1.3 原位(Inplace)操作和非原位操作的区别`_ 了解详情。
.. _3.1.3 原位(Inplace)操作和非原位操作的区别: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/beginner/tensor_cn.html#id3
.. note::
别名支持:参数名 ``input`` 可替代 ``x``,参数名 ``other`` 可替代 ``y``,如 ``floor_divide_(input=tensor_x, other=tensor_y)`` 等价于 ``floor_divide_(x=tensor_x, y=tensor_y)``。
| 项目 | 规范 | 示例 |
|---|---|---|
| 别名说明位置 | 参数描述末尾,句号前 | - **x** (Tensor) - 输入的 Tensor。别名 ``input``` |
| 别名格式 | 2 个反单引号+别名+2 个反单引号 | input 或 dim |
| 多个别名 | 用"或"连接 | 别名 input 或 ``other``` |
| 参数类型 | 可选参数用管道符 | (float|None,可选) 或 (str|None,可选) |
| 关键字参数标题 | "关键字参数"后跟冒号行 | 关键字参数 + 换行 + ::::::::: |
| 关键字参数缩进 | 4 个空格对齐 | - **out** (Tensor,可选) - ... |
| out 参数模板 | 统一说明 | 输出 Tensor,若不为 ``None``,计算结果将保存在该 Tensor 中,默认值为 ``None``。 |
rst 格式:
::- 开头() 包裹 input ${ROOT_DIR} 变量表示根目录,需自行替换为实际路径paddle.Tensor.abs)
paddle.abs)混淆paddle.abs_)