Skip to content

英文API文档贡献指南

Jump to bottom
Chen Long edited this page Mar 30, 2021 · 5 revisions

英文API文档贡献指南

PaddlePaddle 的英文API文档存储于 PaddlePaddle/Paddle 中，采用 Sphinx抽取至官网API文档 。如果想要修改英文API文档，需要按以下流程完成修改。

修改的流程图如下： 图片

一、修改前的准备工作

1.1 Fork

先跳转到 PaddlePaddle/Paddle GitHub 首页，然后单击 Fork 按钮，生成自己仓库下的目录，比如你的 GitHub 用户名为 USERNAME，则生成： https://github.com/USERNAME/Paddle。 图片

1.2 Clone

将你目录下的远程仓库clone到本地。

➜ git clone https://github.com/USERNAME/Paddle
➜ cd Paddle

1.3 创建本地分支

Paddle 目前使用 Git流分支模型进行开发，测试，发行和维护。

所有的 feature 和 bug fix 的开发工作都应该在一个新的分支上完成，一般从 develop 分支上创建新分支。

使用 git checkout -b 创建并切换到新分支。

➜  git checkout -b my-cool-stuff

值得注意的是，在 checkout 之前，需要保持当前分支目录 clean，否则会把 untracked 的文件也带到新分支上，这可以通过 git status 查看。

1.4 下载 pre-commit 钩子工具（若有的话，可以跳过此步骤）

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。

二、正式修改API文档

2.1 新增 API 文档

Paddle 的 API 文档大多定义在 python 层，使用 Sphinx 完成抽取。因此，当你在 python 层新增了一个API时，只需要按照 飞桨API文档书写规范，在新增API定义下添加注释，即可完成英文API文档的新增。如 paddle.all 的 英文API文档就在其定义下的注释中: 图片

注意：有部分API的英文API文档不是按上述方法定义，具体列表见：飞桨特殊API实现。目前，不建议按照此种方式新增API。

2.2 修改 API 文档

Paddle 的API文档大多定义在 python 层，你可以通过 API文档 页面中，每个API声明最后的源代码，找到该API对应的英文源代码文件。如点击 paddle.all 的源代码，就会直接跳转到 paddle.all 的实现。如果你发现API文档中有问题，或者是想要优化API文档，直接修改该文件即可。

图片

注意：有部分API的英文API文档不是按上述方法定义，具体列表见：飞桨特殊API实现,该列表中给出了每个API的文档存储位置，如果你需要修改这部分API，可按照该表找到API对应的源文件进行修改。

三、提交&push

3.1 提交&触发CI单测

  • 修改 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"

3.2 确保本地仓库是最新的

在准备发起 Pull Request 之前，需要同步原仓库（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

3.3 Push 到远程仓库

将本地的修改推送到 GitHub 上，也就是 https://github.com/USERNAME/Paddle。

# 推送到远程仓库 origin 的 my-cool-stuff 分支上
➜  git push origin my-cool-stuff

四、提交PR

在你push后在对应仓库会提醒你进行PR操作：

图片

点击后，按格式填写PR内容，即可。

五、review&merge

提交PR后，可以点击右侧的Reviewers，指定 Paddle 的同学进行 Review。 图片

目前，Paddle 负责API文档的同学是 @TCChenLong，可以直接指定他进行文档Review；此外，你也可以指定 @jzhang533、@saxon-zh、@Heeenrrry、@swtkiwi、@dingjiaweiww等同学review 。

CI

Paddle 中与文档相关的CI 流水线是 PR-CI-CPU-Py2-18(当前的)等，主要对以下几个方面进行检查:

  • 根据『必须有文档的API列表』检查是否有api缺失文档字符串。
  • 将变更所涉及的API的文档字符串（若有的话）中的实例代码抽取出来，若需要执行要能成功运行

图片

如果无法通过该CI，请点击对应CI的details，查看CI运行的的log，并根据log修改你的PR，直至通过CI。

Clone this wiki locally