[Change]修改目前 Paddle docs 中 COPY-FROM 的逻辑 #5941
Conversation
|
感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-5941.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html |
docs/api/copy_codes_from_en_doc.py
Outdated
| else find_codeblock_needed_by_name(cb_name, codeblocks) | ||
| ) | ||
|
|
||
| # we use `cb_name` first, if not exist, then use the first codeblock without name, or codeblocks[0]. |
There was a problem hiding this comment.
或者第一个没有 name 的
为什么要返回第一个没有 name 的呢？这是有必要的吗？
docs/api/gen_doc.py
Outdated
| ) | ||
| .replace("\t", ' ') | ||
| .split("\n") | ||
| ) |
There was a problem hiding this comment.
只是把 Examples 提前了？看起来是一个 hack，目标应该只是提取全部代码块，能否不用 hack 的方式实现呢？
There was a problem hiding this comment.
为什么要返回第一个没有 name 的呢？这是有必要的吗？
只是把 Examples 提前了？看起来是一个 hack，目标应该只是提取全部代码块，能否不用 hack 的方式实现呢？
这两个问题其实可以算是一个问题，我一起回复吧～
简单说，是为了兼顾目前 COPY-FROM 的写法。
因为，目前文档里面使用 COPY-FROM 的地方，基本都没有使用 COPY-FROM: 方法名:名称 的方式，而是 COPY-FROM: 方法名。
也就是说，目前都是默认使用 codeblocks[0]。
原有代码也是这样的处理方式：
return (
codeblocks[0]
if cb_name is None
else find_codeblock_needed_by_name(cb_name, codeblocks)
)理想的方式是：
- 获取到
COPY-FROM所在 rst 文档的具体位置，如，处于哪个方法，以及是在此方法的描述中，还是代码示例中；或者，直接根据方法名:名称进行标注。 - 提取到 docstring 中的示例代码，并标注是在一开始的描述部分还是
Examples中；或者，直接根据:name: xxx进行标注。
如此，就可以进行匹配，其中 name 匹配是最好的方式。
但是，现在的情况是：
- 标注 docstring 中示例代码位置相对简单，而获取 rst 文档中的具体位置就比较麻烦。如果用正则来匹配，可行性和风险都要重新评估，这也是为什么
COPY-FROM要有方法名:名称这样的模式。 - 但是，目前大家大部分都没有用
名称，就导致的目前只能用codeblocks[0]这样相对 hack 的方式...
至于 Examples 提前，其实，是否提前都可以提取所有的示例，但是，如果不提前，那么，如果存在以下的 rst 文档：
...
.. code-block: python
xxx
代码示例
:::::::::
COPY-FROM: paddle.xxx
在 docstring 中会提取到两段代码，两段代码都没有名称，后续匹配的时候，就会把第一段代码转换到 COPY-FROM 的地方，这明显是错误的，单测中也有这个用例。
所以，如果能够规范 COPY-FROM: 方法名:名称 这样的写法，或者，有一种风险较小的方法定位 rst 中的 code-block 与 COPY-FROM，都是可行的方法～
@SigureMo 帮忙看看有没有什么好方法 ～ 🤔
Update 20230620
@SigureMo 请评审 ～ ：） |
|
|
||
| lineno_examples = len(ds_list) | ||
| ds_list += docstr[mo.start() :].replace("\t", ' ').split("\n") | ||
|
|
There was a problem hiding this comment.
这里的逻辑是不是过于复杂了
example_start = float("inf")
for lineno, line in enumerate(docstr.splitlines()):
if re.match("^Examples?:", line.lstrip()):
example_start = lineno
if not google_style or lineno >= example_start:
docstr_list.append(line)类似这样的思路，整体代码会简洁很多
这里不需要 replace 掉 tabs 了，我在 PaddlePaddle/Paddle#54796 会清理掉剩余全部 tabs
不建议按照原来的代码风格用缩写，原来的代码有点……一言难尽:joy:，改这个文件也是辛苦你了
There was a problem hiding this comment.
这。。。有bug。。。example_start 不对～ 😂
改了一下，也加了单测～
请评审！：）
docs/api/copy_codes_from_en_doc.py
Outdated
| for _cb in codeblocks: | ||
| if _cb.get('in_examples'): | ||
| cb = _cb | ||
| break |
There was a problem hiding this comment.
目前的逻辑是：
- 有 name 按照 name 找
- 没有 name 找 Example 下的第一个
- 还是找不到找全局的第一个
我有点担忧的是，这是否会造成混乱，其实如果只有 1、2 或者只有 1、3 我觉得倒没什么，因为逻辑是说得通的，但 1、2、3 都有就有些奇怪了，没有文档很难知道这里面发生了什么
我比较建议，不要直接返回全局第一个，默认就是 Example 下的第一个，Example 外的，强制使用 name 来索引，也即这里的逻辑删掉 3，只保留 1、2，这样仍然可以和现有逻辑保持兼容，而且不会增加额外的心智负担
这样的话可以这样写：
example_codeblocks = [codeblock for codeblock in codeblocks if codeblock.get("in_examples")]
return (
example_codeblocks[0]
if cb_name is None
else find_codeblock_needed_by_name(cb_name, codeblocks)
)There was a problem hiding this comment.
跟我一开始想的一样！！！😆
其实，后面规定 Example 外的，强制使用 name 来索引 就行，我自己也记了个 todo，后面在开发文档里面要写一下，约束开发者的文档写作～～～
就这么办！🎉🎉🎉
Update 20230621
@SigureMo 请评审！：） |
|
我这边没什么问题了，不过我不确定这些单测是否方便合入，这些单测有如下问题：
因此建议不将这些单测合入，这里能确保功能没有问题即可 之后我没什么问题了，修改后我可以直接合入，建议进入下一阶段，开始 COPY-FROM 任务发放，发动社区力量来替换掉现有非 COPY-FROM 的代码块 这一部分可以考虑：
之后就可以发放到群里了，如果端午节这两天就可以拆出来的话，应该响应的会比较多 |
|
删掉了～ 端午... 三倍工资... 🤔 🛶 🎆 |
PR types
New features
PR changes
APIs
Description
中国软件开源创新大赛：飞桨框架任务挑战赛
赛题五：将 xdoctest 引入到飞桨框架工作流中
RFC [Add]将 xdoctest 引入到飞桨框架工作流中v1
ISSUE 赛题五：将 xdoctest 引入到飞桨框架工作流中 Tracking Issue
第一阶段
任务：修改目前 Paddle docs 中 COPY-FROM 的逻辑
docs/api/copy_codes_from_en_doc.py不使用google_style，返回带name的 codeblock，或者第一个没有name的。docs/api/gen_doc.py增加非google_style的处理方法，兼容原有方式。docs/api/test/test_copy_codes_from_en_doc.py单测.gitignore增加 pyc@SigureMo @luotao1 @jzhang533 @sunzhongkai588
请评审，谢谢！：）