Skip to content
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

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

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

watonyweng
Copy link
Contributor

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

@watonyweng watonyweng changed the title fix: Fix the rust script that executes code blocks when running mdbook tests on CI fix: fix rust script that executes code blocks when running mdbook tests on CI May 24, 2024
@watonyweng watonyweng marked this pull request as ready for review May 24, 2024 02:06
@EluvK
Copy link
Contributor

EluvK commented May 24, 2024

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

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

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

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

@watonyweng watonyweng changed the title fix: fix rust script that executes code blocks when running mdbook tests on CI fix: fix rust script that executes in code blocks when running mdbook test on CI May 24, 2024
@watonyweng
Copy link
Contributor Author

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

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

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

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

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

@watonyweng
Copy link
Contributor Author

watonyweng commented May 27, 2024

Hi @sunface , can you approve this PR?

@sunface
Copy link
Owner

sunface commented Jun 13, 2024

抱歉,最近比较忙。

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

@EluvK
Copy link
Contributor

EluvK commented Jun 14, 2024

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

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants