[PaddlePaddle/Paddle][Add] Paddle 代码 CI 中引入 xdoctest 检查

中国软件开源创新大赛：飞桨框架任务挑战赛赛题五：将 xdoctest 引入到飞桨框架工作流中

RFC [Add]将 xdoctest 引入到飞桨框架工作流中v1 ISSUE 赛题五：将 xdoctest 引入到飞桨框架工作流中 Tracking Issue

第一阶段任务：Paddle 代码 CI 中引入 xdoctest 检查

sampcd_processor_readme.md : Xdoctester 的详细设计文档
sampcd_processor_utils.py : 代码检查的相关工具
sampcd_processor_xdoctest.py : Xdoctester 的相关实现
sampcd_processor.py : 原代码检查工具
test_sampcd_processor.py : 原代码检查工具单元测试
test_sampcd_processor_xdoctest.py : Xdoctester 单元测试
requirements.txt : 添加了 xdoctest
beta.py : 修改了其中的示例代码样式，用于检查新工具 Paddle CI 的正确性。

建议先 review sampcd_processor_readme.md : Xdoctester 的详细设计文档，看看还有哪些需要修改的设计～

另外，xdoctest 的 requirement 看看放在 python 目录下是否合适？

@SigureMo @luotao1 @jzhang533 @sunzhongkai588

请评审，谢谢！：）

megemini

你的PR提交成功，感谢你对开源项目的贡献! 请关注后续CI自动化测试结果，详情请参考Paddle-CI手册。 Your PR has been submitted. Thanks for your contribution! Please wait for the result of CI firstly. See Paddle CI Manual for details.

paddle-bot[bot]

辛苦，我看这个 PR 最近还在修改一些文档进行测试，是否已经准备好 review 了呢？准备好的时候可以 @ 一下我

另外我们也测试一下这边和 docs 那边能否正常 copy 这边修改过的源码吧，这边在 commit 里加上 test=docs_preview 就可以在 PR-CI-Paddle-Doc-Preview 流水线看到英文文档了

中文文档那边需要新建一个 PR，然后在 PR 描述里添加 PADDLEPADDLE_PR=55295 即可

SigureMo

一直在等 review ......... 一直没消息，所以这几天就改了几个 codeblock，暂时也没发现什么问题～

中文文档那边需要新建一个 PR

这个是指？

megemini

docs repo

SigureMo

关于什么的 PR？

megemini

docs 端才能触发中文文档 preview 呀，随便创建即可

SigureMo

@SigureMo 建好了～

https://github.com/PaddlePaddle/docs/pull/6031

megemini

Update 20230716

增加 directive 的链接
修改减少正则的空格
修改日期

@SigureMo 请评审！谢谢～

megemini

整体上感觉没什么问题，只是现在 CI 里的 log 是不是有点多？一些 log 是不是可以放在其他 level 里？

SigureMo

我看了一下，好像不是 log 的 level 问题，CI 脚本是开启 debug：

2023-07-13 13:48:25 ++ python sampcd_processor.py --threads=1 --debug gpu

xdoctest 默认跟随命令的 debug：

DEBUG = _boolean_environ('XDOCTEST_DEBUG') or '--debug' in sys.argv

导致这么多日志～～～

xdoctest 这样其实有点问题，我们没有用命令直接调用 xdoctest，而它却通过命令行设置 debug ...

如果要关掉 xdoctest 的 debug，只能在程序里面直接设置 DEBUG 参数，咋整？！

@SigureMo

megemini

这个是可以做到的嘛？如果可以做到的话，我觉得可以一试

SigureMo

我把 xdoctest 的 debug 跟 verbose 关联起来了～

看看目前这样的输出可否？！

@SigureMo

megemini

嗯，https://github.com/PaddlePaddle/Paddle/issues/54705 的最后一个任务有跟踪： 中英文 API 文档特性更新

@jzhang533 辛苦一下负责官网研发的同学了～

另外，这几天我把： 分批次修改已有代码的示例，这个任务划分一下，等第一个批量任务搞定之后，这个就可以开始做起来了～

@SigureMo 看看后面计划怎么做？

megemini

分批次修改已有代码的示例的review量非常大， @megemini @sunzhongkai588 要看一下如何分工么？比如 @megemini 承担下一审？

luotao1

我一人review负担有点太重了，可以简单分工一下吧：

前期（任务发布2周内），涉及的相关pr review都 request @megemini @SigureMo @sunzhongkai588 ,我们需要都能熟悉整个 review 流程和重点，以及测试一下ci的情况。
中后期（任务发布2周后），需要辛苦 @megemini 针对涉及的PR进行初审，初审通过后的PR再request @SigureMo 或 @sunzhongkai588 ，我和001平分一下。

ps：paddle的pr合入都需要我approve，但review的工作我们互相分担一下。

sunzhongkai588

@megemini review 代码有助于拿到 committee 权限

luotao1

@megemini 按我的理解，这个任务的 review 会比 COPY-FROM 容易很多，不需要进行文档的预览，目前示例代码的检查逻辑应该是如果以 >>> 开始则走 xdoctest，如果不是则走旧的检查，新的代码走旧的检查一定会失败（>>> 是不合法的语法），因此基本上通过 CI 是否通过就可以确定修改是否成功了

前期大家都来 review 一方面是让大家都熟悉整个 review 的重点是什么，逐渐完善开发者引导和 reviewer review 流程文档，另一方面也最好注意一下流水线里的 log，看看是否触发了新的 xdoctest 检测，是否都正确通过，这个阶段最好也看一下预览看看是否有问题，如果有问题的话，前期尽可能把工具打磨完善，后期如果再发现这些问题就晚了

按我理解，如果前期打磨完善，工具没问题，基本上看 CI 通过就可以确保 PR 没问题了，review 工作量会小很多

review 代码有助于拿到 committee 权限

关于 committer 可以参考 https://github.com/PaddlePaddle/community/blob/master/contributors/community-membership.md

SigureMo

工作量我简单统计了一下，以目前 2.5.0rc1 为例：

1406 段示例代码
共计 22588 行

这个 PR 我断断续续改了 8 个文件，共计 470+ 行，大约 2～3 个小时的工作量。

大约 6～7 个人 1 小时/天，1 个月的工作量，熟练了之后会比较快。

后面可以按照 1～2 个月的时间来安排。

就难易程度而言，这个改起来相对 COPY-FROM 要简单，大部分时间都是在添加 >>> ... ...

这个星期我把分工、修改示例、工作流之类的前期工作整理一下。

另外，我写了个脚本，把代码先转换一下，再修改起来能快不少：https://github.com/megemini/convert_doctest

@SigureMo @luotao1 @sunzhongkai588 @jzhang533 等我把这个批量任务的 issue 发出来再 @ 大家～：）

megemini

[PaddlePaddle/Paddle][Add] Paddle 代码 CI 中引入 xdoctest 检查

回答