doubter

在 Markdown 文件中测试 Rust 代码块。

概述

此软件包通过将代码块嵌入 Rust 源代码并构建为一个软件包来执行 Markdown 文件中的代码块。这种方法的优势在于依赖关系解析由 cargo 完成。这意味着与更新 Rust 工具链相关的依赖问题不会发生。

入门

doubter 将目标 Markdown 文件嵌入 Rust 代码作为 公共 文档注释。因此，需要为测试代码块创建一个新的软件包，以便与发布的软件包分开。这些软件包通常在 [workspace.members] 中注册。

使用过程宏

将 doubter 的依赖项添加到 Cargo.toml。如果代码块需要某些外部软件包，请指定为 [dev-dependencies] 的成员。

[dependencies]
doubter = "0.1.0"

[dev-dependencies]
rand = "0.5"

然后，修改 src/lib.rs 以指定目标 Markdown 文件的路径。

#[macro_use]
extern crate doubter;

generate_doc_tests! {
    include = "README.md",
    include = "docs/**/*.md",
}

宏 generate_doc_tests!(...) 接受逗号分隔的字段列表。以下是目前支持的字段键

• include - 字符串
  指向要测试的 Markdown 文件（们）路径的 glob 模式。必须是 cargo 的清单目录的相对路径。
• mode - 字符串，可选
  将 Markdown 文件转换为 doctest 的模式。支持的值如下
  • "raw"（默认）: 将 Markdown 文件嵌入 Rust 源代码 原样。
  • "extract"：提取代码块并以 doctest 的形式输出 每个块。
• use_external_doc - 字符串或布尔值，可选
  指定是否使用 #[doc(include = "...")] 来嵌入 Markdown 文件。当此字段启用时，mode 的值将强制设置为 "raw"。

目前，函数式过程宏的实现使用 proc-macro-hack。通过自定义 Derive 的过程宏定义有一些限制，并且 use 样式的导入不符合预期。您可以通过禁用功能标志 hack 来切换到 Macros 1.2 的实现（默认启用此功能标志）

[dependencies.doubter]
version = "0.1.0"
default-features = false

示例

请参阅测试存储库 在 crates/ 内

替代方案

• doc-comment

许可

doubter 在 MIT 许可证 下发布。