mdBook-Keeper

"测试用例的账本。"

mdBook-keeper为mdBook添加了更多测试功能，特别是对第三方crate的支持和编译时测试。我希望它最终能被合并到mdBook中。

此项目的当前目标包括

• 指定在测试mdbook时要包含的第三方crate。 (已完成)
• 在构建过程中运行测试，而不是作为单独的命令。 (已完成)
• 仅在代码已更改时运行测试。 (已完成)
• 能够将编译或构建输出作为书籍的一部分查看（既有助于调试，也可能作为永久输出）。 (待办)

安装

要安装此工具，请运行

$ cargo install mdbook-keeper

然后将它作为预处理器添加。将以下片段添加到您的 book.toml 文件的底部

[preprocessor.keeper]
command = "mdbook-keeper"

最后，按正常方式构建您的书籍

$ mdbook build path/to/book

使用现有项目的Crates

许多mdbook的使用案例中，文档是项目的一个子文件夹。为了简化对这种用例的支持，您可以简单地告诉mdbook-keeper哪个目录包含Cargo.toml（以及可选的Cargo.lock）。为此，在您的 book.toml 文件的 [preprocessor.keeper] 行之后添加以下行

# NOTE: the file Cargo.toml should exist at this path.
manifest_dir = "../../path/to/project/"

因为 rustc 不读取 Cargo.toml 文件，所以它要求任何你想要使用的crate都必须用 extern crate <name>; 或者其 --extern 选项来声明。为了简化操作，如果你总是想要 extern 一个crate，只需在 [preprocessor.keeper] 下写下以下内容。这将把 --extern 选项传递给 rustc。

externs = ["my_crate", "name_here"]

如果你已经构建了现有项目，你可能希望让 mdbook-keeper 使用与项目相同的 target 目录。这意味着在构建书籍和项目时，包不需要在两个不同的位置重新构建。在你的 book.toml 中 [preprocessor.keeper] 行之后添加以下行。

# NOTE: the `debug` folder should exist at this path.
target_dir = "../../path/to/target/"

在独立书籍中使用额外crate

如果你没有现有项目，当前解决方案是在书籍仓库内创建一个最小项目。项目只需包含 Cargo.toml、Cargo.lock 和 src/main.rs（或 src/lib.rs）。将所有必需的依赖项放在 Cargo.toml 中。

然后，将 manifest_dir 指向该目录，如上所示。

与 cargo 工作区和构建特性一起工作

如果你在与 cargo 工作区一起工作，你需要将 --workspace 参数传递给 cargo build 的调用。同样，如果你需要通过启用特定特性来构建你的crate，你需要通过 --features first,second（以逗号分隔的列表）来传递它们。在 mdbook-keeper 配置中，你可以这样做

is_workspace = true
build_features = ["first", "second"]

这两者都是可选的：如果它们不在配置中，则不会将manifest dir视为工作区，也不会启用任何特性。

其他配置选项

所有这些选项都可以放在 book.toml 文件中，在 [preprocessor.keeper] 之后。

• test_dir 这个目录用于存储所有中间工作，包括如果未指定，则包含 target/ 文件夹。如果你不喜欢默认位置（./doctest_cache/），你可以在这里更改它。
• terminal_colors 设置是否在 rustc 输出中显示 ANSI 终端颜色。如果是在 TTY 上，则默认为 true，否则为 false。

关于与 DocTest 的差异的说明

mdbook-keeper 不是一个完美的 doctest 替代品。这是由于几个原因

• 由于大部分代码基于 rust-skeptic，我们使用他们的规则来解析Markdown文件。详见他们的项目，但简而言之，我们不会自动为你插入一个 main() 函数，你必须将代码块标记为 rust 才能使其运行。
• 输出格式不同，主要是因为复制 doctest 似乎是不必要的、复杂的且易碎的。
• 它运行在 mdbook build 上，而不是作为单独的命令。

感谢 Skeptic

本项目的一些代码来自 rust-skeptic 项目。事实上，这个项目最初被命名为 mdbook-skeptic 以表彰他们编写的代码，这些代码在编写这个crate时非常有用。

许可证

本存储库中的所有代码都根据APACHE-2.0或MIT许可证发布。