docs.oneflow.org 自动检查任务

[S882li]

docs.oneflow.org 没有自动检查，还在依赖手工方式检查
最终目标是让 docs.oneflow.org 可以做代码的自动检查。分两步走：
提供一个可以本地运行的脚本，检测 oneflow-documentation 仓库里的代码是否都能正常运行
写个程序，能提取指定markdown文件里的代码块，并运行代码块，并返回是否出错的信息
在以上基础上，继续考虑如何方便 markdown 的作者，如何方便配置程序运行的实际结果和期待结果（不急）
把那个脚本加入到 CI 中（很简单，需要和其它同事沟通，到底谁加）
背景：起步可以参考之前我 fork 和魔改的一个代码：doombeaker/mkcodes: Extract python code from markdown file into python file (github.com)
定时间：
1.1 1 周之内完成，记得开一个 issue，记录自己的经验和进度
1.2 待定

[S882li]

基本情况

1. 拆包 mkdocs.py 将其名称更改为 mkdocs_modified.py 以便下一步修改
2. 发现原代码会将一个 md 文件中每个 ```python [换行] ... ``` 的代码块内的语句分别提取到一个单独文件中，所以如果原md文件中有9块代码块，则会生成9个文件，每个文件包含一个代码块
3. 因此修改逻辑，使得所有代码块合并到一个字符串中
4. 添加 traceback 和 exec() ，将得到的代码运行并在报错进行 traceback （如果不报错会显示ok）

解决问题

• 发现 oneflow-documentation 的仓库中有一些代码块有 bug 会影响 ci 机的运行，预计在上线 ci 后需要进行修改
• 一些文章的代码解读部分会重新遍历之前的代码，因此修改逻辑，避免重复的代码块并入总字符串
• exec() 会出现 bug ，因此使用 os.system('python test.py') 来运行
• 一些代码的正常运行需要多个 gpu 的环境，未知 ci 机是否支持

[S882li]

问题解决2

面对 https://github.com/Oneflow-Inc/oneflow-documentation/blob/master/cn/docs/cookies/amp.md 这样的文档，虽然之前的代码块都是能以正确的顺序拼接并运行通过，但是最后一块的代码是需要被放入之前的指定行数来运行的额外代码，这一点是通过语言说明的，ci机无法轻易变通

粗略想到的解决方法有二：

1. 彻底改变ci机测试逻辑，不以运行通过为目标，而是以代码无错字等较为宽松的标准（此方法也能解决多个gpu才能运行的代码的问题）
2. 在需要插入之前代码的代码块内部加上特殊注释来进行操作（比如无效化此代码块和精准的插入之前的字符串中）

[doombeaker]

相信基础的背景和功能已经有所了解，现在在展开工作中，要考虑具体的和业务逻辑问题：

1. 并不是所有的 code block 是需要运行的，因为有些 code block 里是伪代码，应该跳过。
2. 并不是跑通 code block 就是测试，测试应该是 “跑通，且运行结果符合预期”。因此，要思考如何表示“预期结果”

因此，建议把如何设置哪些 codeblock 要跳过、什么是预期结果这些功能，以某种方式，留给用户。比如配置文件。