英文API文档贡献指南 - PaddlePaddle/docs GitHub Wiki
PaddlePaddle 的英文API文档存储于 PaddlePaddle/Paddle 中,采用 Sphinx抽取至官网API文档 。如果想要修改英文API文档,需要按以下流程完成修改。
先跳转到 PaddlePaddle/Paddle GitHub 首页,然后单击 Fork 按钮,生成自己仓库下的目录,比如你的 GitHub 用户名为 USERNAME,则生成: https://github.com/USERNAME/Paddle。
将你目录下的远程仓库clone到本地。
➜ git clone https://github.com/USERNAME/Paddle
➜ cd Paddle
Paddle 目前使用 Git流分支模型进行开发,测试,发行和维护。
所有的 feature 和 bug fix 的开发工作都应该在一个新的分支上完成,一般从 develop 分支上创建新分支。
使用 git checkout -b
创建并切换到新分支。
➜ git checkout -b my-cool-stuff
值得注意的是,在 checkout
之前,需要保持当前分支目录 clean,否则会把 untracked 的文件也带到新分支上,这可以通过 git status
查看。
Paddle 开发人员使用 pre-commit 工具来管理 Git 预提交钩子。 它可以帮助你格式化源代码(C++,Python),在提交(commit)前自动检查一些基本事宜(如每个文件只有一个 EOL,Git 中不要添加大文件等)。
pre-commit测试是 Travis-CI 中单元测试的一部分,不满足钩子的 PR 不能被提交到 Paddle,首先安装并在当前目录运行它:
➜ pip install pre-commit
➜ pre-commit install
Paddle 使用 clang-format 来调整 C/C++ 源代码格式,请确保 clang-format 版本在 3.8 以上。
注:通过pip install pre-commit
和 conda install -c conda-forge pre-commit
安装的yapf稍有不同,Paddle 开发人员使用的是 pip install pre-commit
。
Paddle 的 API 文档大多定义在 python 层,使用 Sphinx 完成抽取。因此,当你在 python 层新增了一个API时,只需要按照 飞桨API文档书写规范,在新增API定义下添加注释,即可完成英文API文档的新增。如 paddle.all
的 英文API文档就在其定义下的注释中:
注意:有部分API的英文API文档不是按上述方法定义,具体列表见:飞桨特殊API实现。目前,不建议按照此种方式新增API。
Paddle 的API文档大多定义在 python 层。你可以通过以下几种方式找到API文档的路径: 1、在python交互模式中,使用 inspect.getfile(paddle_api) 获取API实现的源文件 2、在API的官网文档中,点击文档声明末尾的源代码链接,跳转至github上对应的源文件 3、在API管理平台上,点击API名称,跳转至github上对应的源文件
注意:有部分API的英文API文档不是按上述方法定义,具体列表见:飞桨特殊API实现,该列表中给出了每个API的文档存储位置,如果你需要修改这部分API,可按照该表找到API对应的源文件进行修改。
- 修改
python/paddle/tensor/math.py
这个文件,并提交这个文件
➜ git status
On branch my-cool-stuff
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: python/paddle/tensor/math.py
no changes added to commit (use "git add" and/or "git commit -a")
➜ git add python/paddle/tensor/math.py
如果你不想提交本次修改,使用 git checkout -- <file>
取消上面对python/paddle/tensor/math.py
文件的提交,可以将它恢复至上一次提交的状态:
➜ git checkout -- python/paddle/tensor/math.py
恢复后重新进行修改并提交文件即可。
- 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
全部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
- 填写提交说明:Git 每次提交代码,都需要写提交说明,让其他人知道这次提交做了哪些改变,可以通过
git commit
完成:
➜ git commit -m "fix all docs bugs"
如果只修改了文档内容,那么可以在 commit 内容中加上 test=document_fix
,跳过不必要的CI检查。CI检查的说明请见附录CI的说明。
➜ git commit -m "fix all docs bugs; test=document_fix"
在准备发起 Pull Request 之前,需要同步原仓库(https://github.com/PaddlePaddle/Paddle )最新的代码。
首先通过 git remote
查看当前远程仓库的名字。
➜ git remote
origin
➜ git remote -v
origin https://github.com/USERNAME/Paddle (fetch)
origin https://github.com/USERNAME/Paddle (push)
这里 origin 是你 clone 的远程仓库的名字,也就是自己用户名下的 Paddle,接下来创建一个原始 Paddle 仓库的远程主机,命名为 upstream。
➜ git remote add upstream https://github.com/PaddlePaddle/Paddle
➜ git remote
origin
upstream
获取 upstream 的最新代码并更新当前分支。
➜ git fetch upstream
➜ git pull upstream develop
将本地的修改推送到 GitHub 上,也就是 https://github.com/USERNAME/Paddle。
# 推送到远程仓库 origin 的 my-cool-stuff 分支上
➜ git push origin my-cool-stuff
在你push后在对应仓库会提醒你进行PR操作,点击后,按格式填写PR内容,即可。
提交PR后,可以指定 Paddle 的同学进行 Review。 目前,Paddle 负责API文档的同学是 @TCChenLong、@jzhang533、@Ligoml、@dingjiaweiww等 。
Paddle 中与文档相关的CI 流水线是 PR-CI-CPU-Py2(develop)
等,主要对以下几个方面进行检查:
- 根据『必须有文档的API列表』检查是否有api缺失文档字符串。
- 将变更所涉及的API的文档字符串(若有的话)中的实例代码抽取出来,若需要执行要能成功运行
如果无法通过该CI,请点击对应CI的details,查看CI运行的的log,并根据log修改你的PR,直至通过CI。