rust-course icon indicating copy to clipboard operation
rust-course copied to clipboard

fix: fix rust script that executes in code blocks when running `mdbook test` on CI

Open watonyweng opened this issue 1 year ago • 5 comments

  • chore: replace rust with rust,ignore,mdbook-runnable
  • chore: add console in blockcode
  • fix: fix relative directory errors when copying files

watonyweng avatar May 24 '24 02:05 watonyweng

如果所有代码块都是跳过的话,执行 mdbook test 的意义就不大了。

我昨天说这个工作量还挺大时的想法...要具体根据每个地方的场景,合理的选择适当的标记,比如这些场景:

  • 对于正确的示例代码是需要运行并且成功的,那就要执行,CI 运行 test 可以保证代码没写错。
  • 对于演示错误的代码是需要运行且期望失败的,就要跳过test,但允许读者运行 (如你做的,加上 ignore, mdbook-runnable)
  • 对于一些片段代码,需要根据上下文情况判断这里是要执行还仅仅是为丰富讲解,有的地方可以在最后加上可运行的完整代码,这样中间的片段代码块都不必执行,加上 ignore
  • 还有 no_run 这个标记,有的代码块我们期望能编译成功,但是不太需要运行(比如不输出任何结果),就可以加这个,用 CI 保证代码没写错。

但如果仅仅是为了屏蔽掉错误,不如去掉 CI 里的 test 步骤? 保证合入的代码能 build && deploy 即可。

EluvK avatar May 24 '24 03:05 EluvK

如果所有代码块都是跳过的话,执行 mdbook test 的意义就不大了。

我昨天说这个工作量还挺大时的想法...要具体根据每个地方的场景,合理的选择适当的标记,比如这些场景:

  • 对于正确的示例代码是需要运行并且成功的,那就要执行,CI 运行 test 可以保证代码没写错。
  • 对于演示错误的代码是需要运行且期望失败的,就要跳过test,但允许读者运行 (如你做的,加上 ignore, mdbook-runnable)
  • 对于一些片段代码,需要根据上下文情况判断这里是要执行还仅仅是为丰富讲解,有的地方可以在最后加上可运行的完整代码,这样中间的片段代码块都不必执行,加上 ignore
  • 还有 no_run 这个标记,有的代码块我们期望能编译成功,但是不太需要运行(比如不输出任何结果),就可以加这个,用 CI 保证代码没写错。

但如果仅仅是为了屏蔽掉错误,不如去掉 CI 里的 test 步骤? 保证合入的代码能 build && deploy 即可。

我同意你的观点,使用 mdbook test 是为了检查 md 文件是否符合要求,针对于代码块中的Rust代码,可能需要借助其它方式进行测试。
@sunface 烦请给点意见呗

watonyweng avatar May 24 '24 06:05 watonyweng

Hi @sunface , can you approve this PR?

watonyweng avatar May 27 '24 11:05 watonyweng

抱歉,最近比较忙。

能帮忙解释下 ignore,mdbook-runnable 新加的参数吗?

sunface avatar Jun 13 '24 06:06 sunface

能帮忙解释下 ignore,mdbook-runnable 新加的参数吗?

@sunface 这个PR上面有解释,ignore 就会在执行 mdbook test 的时候跳过这个代码段;mdbook-runnable 就是在生成的书里面还是有让读者可以运行的按钮。

我的意见还是:这个要改成最终正确的形态很费时间精力,目前这个PR里的替换改动不如直接 CI 里不跑 test 步骤更省事。

EluvK avatar Jun 14 '24 08:06 EluvK

我的意见还是:这个要改成最终正确的形态很费时间精力,目前这个PR里的替换改动不如直接 CI 里不跑 test 步骤更省事。

非常赞同

sunface avatar Sep 05 '24 04:09 sunface

@watonyweng 感谢这么棒的 PR,不过我也比较赞同 @EluvK 的观点,所以先关闭了哈。

sunface avatar Sep 05 '24 04:09 sunface