-
Notifications
You must be signed in to change notification settings - Fork 762
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Docs][hook] add a pre-commit hook to automatically insert space to cn and en char #4973
[Docs][hook] add a pre-commit hook to automatically insert space to cn and en char #4973
Conversation
感谢你贡献飞桨文档,文档预览构建中,Docs-New 跑完后即可预览,预览链接:http://preview-pr-4973.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html |
✅ This PR's description meets the template requirements! |
This comment was marked as duplicate.
This comment was marked as duplicate.
b936275
to
bc189d9
Compare
This comment was marked as outdated.
This comment was marked as outdated.
4202726
to
44480de
Compare
a37c3d0
to
231f8db
Compare
@@ -11,7 +11,7 @@ function filter_cn_api_files() { | |||
local __resultvar=$2 | |||
local need_check_files="" | |||
for file in `echo $git_files`;do | |||
grep "code-block" ../docs/$file > /dev/null | |||
grep 'code-block:: python' ../docs/$file > /dev/null |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
原来 CI 中有部分示例代码因为 no sample code 问题而报错,这是因为在这里筛选是否 need check 的文件时仅仅 check 了是否包含 code-block
,然而有些文件是包含一些非可运行的 code-block
的,比如 code-block:: text
,这些文件之后传入 chinese_samplecode_processor.py 就会报 no sample code 错误
因此这里收缩检查条件,仅仅包含 code-block:: python
才进行后续 check
目前遇到该问题的文件有以下 8 个,这 8 个文件均不会通过 grep 'code-block:: python' $filename
的检查,也就不会传入后续 check
- docs/api/paddle/add_n_cn.rst
- docs/api/paddle/distributed/launch_cn.rst
- docs/api/paddle/incubate/nn/functional/fused_multi_head_attention_cn.rst
- docs/api/paddle/multiplex_cn.rst
- docs/api/paddle/profiler/make_scheduler_cn.rst
- docs/api/paddle/squeeze_cn.rst
- docs/api/paddle/text/Overview_cn.rst
- docs/api/paddle/uniform_cn.rst
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
修改后 CI 不再出现 no sample code 的问题
# required: gpu | ||
import paddle | ||
event = paddle.device.cuda.Event() | ||
COPY-FROM: paddle.device.cuda.Event |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
其中一个 API 需要同时修改中文文档加上 :name:
才可以,因此额外提了 PaddlePaddle/Paddle#44679
.pre-commit-config.yaml
Outdated
files: \.md$ | ||
files: \.md$|\.rst$ | ||
- id: trailing-whitespace | ||
files: \.md$ | ||
files: \.md$|\.rst$ | ||
- repo: https://github.com/Lucas-C/pre-commit-hooks | ||
rev: v1.0.1 | ||
hooks: | ||
- id: forbid-crlf | ||
files: \.md$ | ||
files: \.md$|\.rst$ | ||
- id: remove-crlf | ||
files: \.md$ | ||
files: \.md$|\.rst$ | ||
- id: forbid-tabs | ||
files: \.md$ | ||
files: \.md$|\.rst$ | ||
- id: remove-tabs | ||
files: \.md$ | ||
files: \.md$|\.rst$ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
reStructureText 和 Markdown 同样是用于书写文档的文本文件,都应当进行相关检查和修复,以避免相关格式问题再次发生(其实这些 hook 对于 YAML、Python 等等代码文件也适用,也可以考虑删除 files
字段,使其应用于全部文本文件)
关于在中英文中自动添加空格,目前已经有了一个 hook(https://github.com/ShigureLab/dochooks ,于 #5083 测试),但不能确定其稳定性(虽然我目前用着还不错,但毕竟还没经过太多的检验),因此可在充分检验之后再考虑添加(希望有同学帮忙测试呀~~~)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
我在本地使用hook对所有文件进行格式化,检查了十多个文件,结果均正常。可以考虑加上该hook试运行一段时间。
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
好的,我将那个 hook 也一并放在这个 PR~
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
hook的版本可以按照Paddle仓库的配置文件统一下:
Lucas-C/pre-commit-hooks->v1.1.14
yapf->v0.32.0
pre-commit/pre-commit-hooks->v4.1.0
应当只剩 2 个示例代码问题了,都是从 Overview_cn.rst 提取出来的示例代码,一个是
主要是一些依赖没有装(tqdm 等) 另一个是
这是因为该示例代码是分段渐进叙述的,每一段都不是完整的示例代码 这些都可以考虑直接加入到 此外,由于我们现在示例代码已经基本全部采用 COPY-FROM 取代,因此也可以考虑取消 docs repo 里的示例代码检查,将示例代码检查完全交给 Paddle repo 里的 CI 来进行 |
有些可能是 docufix --all-rules --ignore-globs='docs/api/paddle/fluid/**' '**/*.md' '**/*.rst' --fix 也就是 ignore 了 fluid 下的,目前除了 fluid 下的文档应该都没有问题 如果有必要的话我把 fluid 下的也一并修了 |
配置文件已更新完毕~ |
暂时先不更新吧,fluid在逐渐退场。 |
刚刚才出现的新冲突 😂,已经 merge 并 resolve 了 |
之后是一些 COPY-FROM 的修改,确保 COPY-FROM 能正常显示 以及合并 upstream 并重新格式化
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM for docs
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
随便写了个小工具 docufix 来自动在中英文之间增加空格(参考规范:飞桨文档写作规范#12-文本),并将自动在中英文加空格的功能提取到一个 pre-commit hook 中,置于 https://github.com/ShigureLab/dochooks
本 PR 利用 docufix 统一修复历史遗留未加空格的问题,并添加 dochooks 里的 hook,以规范之后的 commit
另外将现有的一些其他格式问题一并修复:
并且将这些对应的 pre-commit hooks 也应用到了 rst 文件,避免这些问题再次出现
docufix 每次修复时所用的命令(点击展开)
由于 CI 遇到了 26 个示例代码错误,因此逐一修复了了(包含一些
COPY-FROM
),相关修复方案见下面的 comments英文文档同步 PR
PaddlePaddle/Paddle#44679
PADDLEPADDLE_PR=44679