文档贡献指南-使用文档-PaddlePaddle深度学习平台

PaddlePaddle 的文档存储于 PaddlePaddle/docs 中，之后通过技术手段转为 HTML 文件后呈现至官网文档 。官网文档和 docs 的对应关系如下：

修改前的准备工作

Fork

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

Clone

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

git clone https://github.com/USERNAME/docs
cd docs

创建本地分支

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

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

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

git checkout -b my-cool-stuff

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

执行 Git 的 checkout 命令以创建或切换到一个新的分支之前，你需要确保当前的工作目录中没有未提交（untracked）的文件或者未完成的更改。这是因为当你从一个分支切换到另一个分支时，Git 会尝试复制当前分支的状态到新分支，包括所有未提交的更改和未跟踪的文件。如果你不希望这些更改被带到新分支上，你需要在切换分支之前处理它们。

以下是详细解释：

1. 保持当前分支目录 clean：

   • "Clean" 在 Git 中意味着工作目录中没有未提交的更改。这包括未跟踪的文件（untracked files）、已修改但未暂存的文件（modified but not staged files）以及已暂存但未提交的文件（staged but not committed files）。

2. 使用 git status 查看：

   • git status 命令用于检查当前工作目录的状态。它会显示所有未提交的更改和未跟踪的文件，帮助你了解当前分支的状态。

3. 未跟踪的文件（Untracked files）：

   • 未跟踪的文件是指那些在工作目录中存在，但还没有被 Git 跟踪的文件。这些文件不会出现在 git diff 的输出中，除非你使用 git diff --untracked。

4. 切换分支时的影响：

   • 当你从一个分支切换到另一个分支时，Git 会尝试将当前分支的状态复制到新分支。如果你的工作目录中有未提交的更改或未跟踪的文件，这些更改和文件也会被带到新分支，这可能不是你期望的结果。

5. 如何处理未提交的更改和未跟踪的文件：

   • 如果你想要保留这些更改，你可以将它们暂存（git add）并提交（git commit）。

   • 如果你想要临时保存这些更改，可以使用 git stash 来保存当前的工作进度，然后在新分支上使用 git stash pop 来恢复。

   • 如果你确定这些更改不重要，可以使用 git clean 来删除未跟踪的文件，或者使用 git reset 来撤销已暂存的更改。

安装 pre-commit 工具（若有的话，可以跳过此步骤）

Paddle 开发人员使用 pre-commit 工具来管理 Git 预提交钩子。它可以帮助你格式化源代码（C++，Python），在提交（commit）前自动检查一些基本事宜（如每个文件只有一个 EOL，Git 中不要添加大文件等）。

pre-commit 测试是 CI 流水线中测试的一部分，不满足钩子的 PR 不能被提交到 Paddle，首先安装并在当前目录运行它：

pip install pre-commit==2.17.0
pre-commit install

注：通过 pip install pre-commit 和 conda install -c conda-forge pre-commit 安装的 pre-commit 稍有不同，Paddle 开发人员使用的是 pip install pre-commit。

正式修改文档

根据官网文档和 docs 的对应关系，确定要修改/新增的文档路径，然后修改或者新增。

新增文档

当你要新增文档时，需要参考上述的对应关系，找到合适的目录，新建 Markdown 或 reStructuredText 文件。中英文文档存储在同一路径下，其中，中文文档的后缀为 cn.md/rst，英文文档的后缀为 en.md/rst。

在新增文件后，还需要在目录文件中添加该文件的索引。目录文件一般是 index_cn.rst/index_en.rst，需要在文件的 .. toctree:: 部分添加该文件的索引。

如在「文档」->「使用教程」->「动态图转静态图」中新增「报错调试」，首先需要在 docs/guides/jit/ 中 新建 debugging_cn.md，debugging_en.md 文件。之后，在 docs/guides/jit/index_cn.rst 的 toctree 部分，新增 debugging_cn.md 的索引，合入后即可展示到官网。

..  toctree::
    :hidden:

    basic_usage_cn.md
    principle_cn.md
    grammar_list_cn.md
    case_analysis_cn.md
    debugging_cn.md      # 新增索引

修改文档

修改文档，可以通过文档的 URL，确定文档的源文件。 如「文档」->「使用教程」->「动态图转静态图」中「报错调试」的文档 URL 为：https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/jit/debugging_cn.html，URL 路径中，guides/jit/debugging_cn.html 即对应 (docs/)guides/jit/debugging_cn.md , 因此，可以很快的确定文档的源文件，然后直接修改即可。

提交&push

提交&触发CI单测

• 修改 docs/guides/jit/debugging_cn.md 这个文件，并提交这个文件

➜ 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:   paddle/tensor/math/all_cn.rst

no changes added to commit (use "git add" and/or "git commit -a")

➜ git add docs/guides/jit/debugging_cn.md

如果你不想提交本次修改，使用 git checkout -- <file> 取消上面对 docs/guides/jit/debugging_cn.md 文件的提交，可以将它恢复至上一次提交的状态:

➜ git checkout -- docs/guides/jit/debugging_cn.md

恢复后重新进行修改并提交文件即可。

• commit ：提交本地更改

每次 git commit 都需要写提交说明，方便其他人了解每次提交做了哪些改变，可以通过 git commit -m <commit_message> 完成。

➜ git commit -m "fix docs bugs"
check for merge conflicts................................................Passed
check for broken symlinks............................(no files to check)Skipped
detect private key.......................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
CRLF end-lines remover...................................................Passed
Tabs remover.............................................................Passed
CN-[whitespace]-EN fixer.............................(no files to check)Skipped
ruff.....................................................................Passed
ruff-format..............................................................Passed
[my-cool-stuff ee8f4441f] fix docs bugs
 1 file changed, 19 insertions(+), 34 deletions(-)

注意：git commit 执行后会进行代码预检测，不能出现失败的情况，如果有 failed 的检测项需先处理，才能继续后续步骤。

确保本地仓库是最新的

在准备发起 Pull Request 之前，需要同步原仓库（https://github.com/PaddlePaddle/docs）最新的代码。

首先通过 git remote 查看当前远程仓库的名字。

➜  git remote
origin
➜  git remote -v
origin  https://github.com/USERNAME/docs (fetch)
origin  https://github.com/USERNAME/docs (push)

这里 origin 是你 clone 的远程仓库的名字，也就是自己用户名下的 Paddle，接下来创建一个原始 Paddle 仓库的远程主机，命名为 upstream。

upstream：这是你给远程仓库起的一个名字，通常用作远程仓库的默认引用。在 Git 中，upstream 这个词常用来指代项目的原始或官方仓库，但你也可以使用任何其他名字。

当你执行这个命令后，你将能够在本地仓库中通过 upstream 这个名字来引用和操作远程仓库。例如，你可以使用以下命令来从远程仓库拉取最新的代码：

➜  git remote add upstream https://github.com/PaddlePaddle/docs
➜  git remote
origin
upstream

origin是你fork的仓库，upstream是官方原仓库

获取 upstream 的最新代码并更新develop分支。

➜  git fetch upstream
➜  git pull upstream develop

如果在pull中遇到

可以使用以下命令进行合并，关于rebase有机会单开讲解。

➜ git pull --no-rebase upstream develop

随后我们需要切换到my-cool-stuff，在这里merge本地develop分支，从而保证我们的代码是最新的。

➜  git checkout my-cool-stuff
➜  git merge develop

Push到远程仓库

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

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

提交PR

在你 push 后在对应仓库会提醒你进行 PR 操作，点击后，按格式填写 PR 内容，即可。

review & merge

提交 PR 后，可以指定 Paddle 的同学进行 Review。目前 Paddle 负责文档的同学是 @sunzhongkai588、@Ligoml、@jzhang533 等 。

CI

Paddle 中与文档相关的 CI 流水线是 Docs-NEW 等，主要对以下几个方面进行检查:

• 检查开发者是否已经签署 CLA

• 检查增量修改的 API 是否需要相关人员审核

• 检查 API 示例代码是否能正常从英文文档 copy

• 检查渲染后的文档是否存在 WARNING 或 ERROR

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