Skip to content

Commit

Permalink
[docs] update codestyle check guide and docs dev guide (PaddlePaddle#…
Browse files Browse the repository at this point in the history 
…6205)

* [docs] update codestyle check guide

* remove autoflake in example

* add isort

* update 「文档贡献指南」

* remove clang-format in docs guide

* fix basic_usage suffix
  • Loading branch information
@SigureMo
SigureMo authored Sep 26, 2023
1 parent 3ed3275 commit f6e6e3a
Show file tree
Hide file tree
Showing 5 changed files with 51 additions and 254 deletions.
81 changes: 39 additions & 42 deletions docs/dev_guides/docs_contributing_guides_cn.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,19 @@ PaddlePaddle 的文档存储于 [PaddlePaddle/docs](https://github.com/PaddlePad

| 官网 | docs |
| -- | -- |
|[文档/安装说明](https://www.paddlepaddle.org.cn/documentation/docs/zh/install/index_cn.html) | [docs/docs/install](https://github.com/PaddlePaddle/docs/tree/develop/docs/install) |
| [文档/使用教程](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/index_cn.html) | [docs/docs/guides](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides) |
| [文档/应用实践](https://www.paddlepaddle.org.cn/documentation/docs/zh/tutorial/index_cn.html) | [docs/docs/tutorial](https://github.com/PaddlePaddle/docs/tree/develop/docs/tutorial) |
| [文档/API 文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html) | [docs/docs/api](https://github.com/PaddlePaddle/docs/tree/develop/docs/api) |
| [文档/常见问题与解答](https://www.paddlepaddle.org.cn/documentation/docs/zh/faq/index_cn.html) | [docs/docs/faq](https://github.com/PaddlePaddle/docs/tree/develop/docs/faq) |
| [文档/Release Note](https://www.paddlepaddle.org.cn/documentation/docs/zh/release_note_cn.html) | [docs/docs/release_note_cn.md](https://github.com/PaddlePaddle/docs/blob/develop/docs/release_note_cn.md) |
| [文档/安装说明](https://www.paddlepaddle.org.cn/documentation/docs/zh/install/index_cn.html) | [docs/install](https://github.com/PaddlePaddle/docs/tree/develop/docs/install) |
| [文档/使用教程](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/index_cn.html) | [docs/guides](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides) |
| [文档/应用实践](https://www.paddlepaddle.org.cn/documentation/docs/zh/practices/index_cn.html) | [docs/practices](https://github.com/PaddlePaddle/docs/tree/develop/docs/practices) |
| [文档/API 文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html) | [docs/api](https://github.com/PaddlePaddle/docs/tree/develop/docs/api) |
| [文档/常见问题与解答](https://www.paddlepaddle.org.cn/documentation/docs/zh/faq/index_cn.html) | [docs/faq](https://github.com/PaddlePaddle/docs/tree/develop/docs/faq) |
| [文档/Release Note](https://www.paddlepaddle.org.cn/documentation/docs/zh/release_note_cn.html) | [docs/release_note_cn.md](https://github.com/PaddlePaddle/docs/blob/develop/docs/release_note_cn.md) |

## 一、修改前的准备工作

### 1.1 Fork
先跳转到 [PaddlePaddle/docs](https://github.com/PaddlePaddle/docs) GitHub 首页，然后单击 Fork 按钮，生成自己仓库下的目录，比如你的 GitHub 用户名为 USERNAME，则生成： https://github.com/USERNAME/docs。
![图片](http://bos.bj.bce-internal.sdns.baidu.com/agroup-bos-bj/bj-adbd631fa37a3bb3a313e723b17fe634764eebfe)
先跳转到 [PaddlePaddle/docs](https://github.com/PaddlePaddle/docs) GitHub 首页，然后单击 Fork 按钮，生成自己仓库下的目录，比如你的 GitHub 用户名为 USERNAME，则生成： https://github.com/USERNAME/docs。

![fork repo](https://github.com/PaddlePaddle/docs/blob/develop/docs/dev_guides/images/docs-contributing-guides-fork-repo.png?raw=true)

### 1.2 Clone
将你目录下的远程仓库 clone 到本地。
Expand All @@ -31,27 +32,25 @@ docs 目前使用 [Git 流分支模型](https://nvie.com/posts/a-successful-git-

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

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

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

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

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

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

```
➜ pip install pre-commit
➜ pip install pre-commit==2.17.0
➜ 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``。
**注**：通过 `pip install pre-commit` 和 `conda install -c conda-forge pre-commit` 安装的 pre-commit 稍有不同，Paddle 开发人员使用的是 `pip install pre-commit`。

## 二、正式修改文档

Expand All @@ -61,34 +60,32 @@ Paddle 使用 clang-format 来调整 C/C++ 源代码格式，请确保 clang-for

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

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

如在 文档 -> 使用教程 -> 动态图转静态图 中新增 《调试方法》，首先需要在 [docs/guides/04_dygraph_to_static](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/04_dygraph_to_static) 中 新建 `debugging_cn.md`，`debugging_en.md` 文件。之后，在 [docs/guides/04_dygraph_to_static/index_cn.rst](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/04_dygraph_to_static/index_cn.rst) 的 `toctree` 部分，新增 `debugging_cn.md` 的索引，合入后即可展示到官网。
```
如在「文档」->「使用教程」->「动态图转静态图」中新增「报错调试」，首先需要在 [docs/guides/jit/](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/jit/index_cn.html) 中 新建 `debugging_cn.md`，`debugging_en.md` 文件。之后，在 [docs/guides/jit/index_cn.rst](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/jit/index_cn.html) 的 `toctree` 部分，新增 `debugging_cn.md` 的索引，合入后即可展示到官网。

```rst
.. toctree::
:hidden:
basic_usage_cn.rst
program_translator_cn.rst
grammar_list_cn.rst
input_spec_cn.rst
error_handling_cn.md
debugging_cn.md # 新增索引
basic_usage_cn.md
principle_cn.md
grammar_list_cn.md
case_analysis_cn.md
debugging_cn.md # 新增索引
```



### 2.2 修改文档

修改文档，可以通过文档的 URL，确定文档的源文件。 如 文档 -> 使用教程 -> 动态图转静态图 中 《调试方法》的文档 URL 为：[https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/04_dygraph_to_static/debugging_cn.html](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/04_dygraph_to_static/debugging_cn.html)，URL 路径中，`guides/04_dygraph_to_static/debugging_cn.html` 即对应 `(docs/docs/)guides/04_dygraph_to_static/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
## 三、提交 & push


### 3.1 提交&触发 CI 单测

- 修改 ``guides/04_dygraph_to_static/debugging_cn.md`` 这个文件，并提交这个文件
- 修改 `docs/guides/jit/debugging_cn.md` 这个文件，并提交这个文件

```
➜ git status
Expand All @@ -100,13 +97,13 @@ modified: paddle/tensor/math/all_cn.rst
no changes added to commit (use "git add" and/or "git commit -a")
➜ git add guides/04_dygraph_to_static/debugging_cn.md
➜ git add docs/guides/jit/debugging_cn.md
```

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

```
➜ git checkout -- guides/04_dygraph_to_static/debugging_cn.md
➜ git checkout -- docs/guides/jit/debugging_cn.md
```
恢复后重新进行修改并提交文件即可。

Expand All @@ -126,7 +123,7 @@ cpplint..............................................(no files to check)Skipped
pylint...................................................................Passed
copyright_checker........................................................Passed
```
全部 Passed 或 Skipped 后，即可进入下一步。如果有 Failed 文件，则需要按照规范，修改出现 Failed 的文件后，重新 ``git add -> pre-commit`` ，直至没有 Failed 文件。
全部 Passed 或 Skipped 后，即可进入下一步。如果有 Failed 文件，则需要按照规范，修改出现 Failed 的文件后，重新 `git add` -> `pre-commit`，直至没有 Failed 文件。
```
➜ pre-commit
CRLF end-lines remover...............................(no files to check)Skipped
Expand Down Expand Up @@ -158,7 +155,7 @@ copyright_checker........................................................Passed

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

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

```
➜ git remote
Expand Down Expand Up @@ -198,18 +195,18 @@ upstream
在你 push 后在对应仓库会提醒你进行 PR 操作，点击后，按格式填写 PR 内容，即可。


## 五、review&merge
## 五、review & merge

提交 PR 后，可以指定 Paddle 的同学进行 Review。目前 Paddle 负责文档的同学是 @TCChenLong、@jzhang533、@saxon-zh、@Heeenrrry、@dingjiaweiww 等 。
提交 PR 后，可以指定 Paddle 的同学进行 Review。目前 Paddle 负责文档的同学是 [@sunzhongkai588](https://github.com/sunzhongkai588)、[@Ligoml](https://github.com/Ligoml)、[@jzhang533](https://github.com/jzhang533) 等 。


## CI

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

- 检查 PR CLA
- 检查开发者是否已经签署 CLA
- 检查增量修改的 API 是否需要相关人员审核
- 若需要执行示例代码则执行看能否正常运行
- 检查 API 示例代码是否能正常从英文文档 copy
- 检查渲染后的文档是否存在 WARNING 或 ERROR

如果无法通过该 CI，请点击对应 CI 的 details，查看 CI 运行的的 log，并根据 log 修改你的 PR，直至通过 CI。
未选择任何文件
18 changes: 11 additions & 7 deletions docs/dev_guides/git_guides/codestyle_check_guide_cn.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 代码风格检查指南

整洁、规范的代码风格，能够保证代码的可读性、易用性和健壮性。Paddle 使用 [pre-commit](http://pre-commit.com/) 工具进行代码风格检查。它可以帮助检查提交代码的不规范问题并格式化（当前会检查 C++、Python 和 CMake 语言的代码）。诸如 flake8、cpplint 等工具能提前发现代码的潜在静态逻辑错误，提高开发效率。
整洁、规范的代码风格，能够保证代码的可读性、易用性和健壮性。Paddle 使用 [pre-commit](http://pre-commit.com/) 工具进行代码风格检查。它可以帮助检查提交代码的不规范问题并格式化（当前会检查 C++、Python 和 CMake 语言的代码）。诸如 ruff、cpplint 等工具能提前发现代码的潜在静态逻辑错误，提高开发效率。

在 Paddle CI 中，由 PR-CI-Codestyle-Check 流水线对提交的 PR 进行代码风格检查，若该流水线执行失败，PR 将**无法合入**到 Paddle 仓库。此时需要根据流水线日志的报错信息，在本地修改代码，再次提交。一般情况下，本地使用 `pre-commit` 进行代码风格检查的结果和 PR-CI-Codestyle-Check 流水线结果是一致的。下面介绍 `pre-commit` 的本地安装与使用方法。

Expand Down Expand Up @@ -43,13 +43,15 @@ Tabs remover (C++).......................................................Passed
Tabs remover (Python)................................(no files to check)Skipped
copyright_checker........................................................Passed
black................................................(no files to check)Skipped
isort................................................(no files to check)Skipped
flake8...............................................(no files to check)Skipped
autoflake............................................(no files to check)Skipped
ruff.................................................(no files to check)Skipped
pylint...............................................(no files to check)Skipped
clang-format.............................................................Failed
- hook id: clang-format
- files were modified by this hook
cpplint..................................................................Passed
clang-tidy...............................................................Passed
auto-generate-cmakelists.............................(no files to check)Skipped
cmake-format.........................................(no files to check)Skipped
CMake Lint...........................................(no files to check)Skipped
Expand Down Expand Up @@ -81,15 +83,17 @@ Date: xxx
| 检查工具名称 | 作用 | 当前版本 |
|---|---|---|
| [pre-commit](https://github.com/pre-commit/pre-commit) | hook 管理工具 | 2.17.0 |
| [pre-commit/pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks) | pre-commit 官方支持的 hook，执行一些通用检查 | 4.1.0 |
| [Lucas-C/pre-commit-hooks](https://github.com/Lucas-C/pre-commit-hooks.git) | 社区维护的一些通用的 hook，含将 CRLF 改为 LF、移除 Tab 等 hook | 1.1.14 |
| [pre-commit/pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks) | pre-commit 官方支持的 hook，执行一些通用检查 | 4.4.0 |
| [Lucas-C/pre-commit-hooks](https://github.com/Lucas-C/pre-commit-hooks.git) | 社区维护的一些通用的 hook，含将 CRLF 改为 LF、移除 Tab 等 hook | 1.5.1 |
| [copyright_checker](https://github.com/PaddlePaddle/Paddle/blob/develop/tools/codestyle/pylint_pre_commit.hook) | Copyright 检查 | 本地脚本 |
| [black](https://github.com/psf/black) | Python 代码格式化 | 22.8.0 |
| [flake8](https://github.com/PyCQA/flake8) | Python 代码风格检查 | 4.0.1 |
| [autoflake](https://github.com/PyCQA/autoflake) | Python Flake8 部分错误码自动修复 | 1.7.7 |
| [black](https://github.com/psf/black) | Python 代码格式化 | 23.3.0 |
| [isort](https://github.com/pycqa/isort) | Python 代码格式化（仅 import 区域） | 5.11.5 |
| [flake8](https://github.com/PyCQA/flake8) | Python 代码风格检查（即将被 Ruff 完全替换） | 5.0.4 |
| [ruff](https://github.com/astral-sh/ruff) | Python 代码风格检查 | 0.0.289 |
| [pylint](https://github.com/PyCQA/pylint/) | Python 代码风格检查，目前仅用于检查示例代码 | 2.12.0 |
| [clang-format](https://github.com/llvm/llvm-project/tree/main/clang/tools/clang-format) | C++ 代码格式化 | 13.0.0 |
| [cpplint](https://github.com/cpplint/cpplint) | C++ 代码风格检查 | 1.6.0 |
| [clang-tidy](https://github.com/llvm/llvm-project/tree/main/clang-tools-extra/clang-tidy) | C++ 代码风格检查 | 15.0.2.1 |
| [cmake-format](https://github.com/cheshirekow/cmake-format-precommit) | CMake 代码格式化 | 0.6.13 |
| [cmake-lint](https://github.com/cmake-lint/cmake-lint)| CMake 代码风格检查 | 1.4.2 |
Expand Down
Binary file added docs/dev_guides/images/docs-contributing-guides-fork-repo.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit f6e6e3a

Please sign in to comment.