成为 Rust 文档的 Skeptic

通过 Cargo 测试你的 Rust Markdown。

入门指南

将以下内容放入 Cargo.toml 以添加 little-skeptic 依赖项

[build-dependencies]
little-skeptic = "0.14"

[dev-dependencies]
little-skeptic = "0.14"

同样在 Cargo.toml 的 [package] 部分添加

build = "build.rs"

这将通过 构建脚本 来添加构建脚本，通过该脚本您将告诉 Skeptic 从一组 Markdown 文件中构建测试用例。

在 build.rs 中写入以下内容以测试 README.md 中的所有 Rust 代码块

extern crate little_skeptic;

fn main() {
    // generates doc tests for `README.md`.
    little_skeptic::generate_doc_tests(&["README.md"]);
}

如果您想测试多个 Markdown 文件，只需构建一个文件名列表，并将其提供给 generate_doc_tests。为了帮助您，方法 markdown_files_of_directory 将创建这样的列表，列出指定目录中的 Markdown 文件。您可以像喜欢的那样添加更多文件到这个列表中

extern crate little_skeptic;

use little_skeptic::*;

fn main() {
    // Add all markdown files in directory "book/".
    let mut mdbook_files = markdown_files_of_directory("book/");
    // Also add "README.md" to the list of files.
    mdbook_files.push("README.md".into());
    generate_doc_tests(&mdbook_files);
}

最后，在 tests/skeptic.rs 中放置以下宏，将生成的测试用例与 cargo test 绑定

include!(concat!(env!("OUT_DIR"), "/skeptic-tests.rs"));

现在，README.md 中的任何 Rust 代码块都将通过 cargo test 进行测试。

用户指南

Rust Skeptic 不基于 rustdoc。在许多情况下，它的行为类似，但并非全部如此。以下是 Skeptic 系统的概述。

注意：此 README.md 文件本身由 Rust Skeptic 进行测试。因为它展示了如何使用 Markdown 语法，所以该文档的标记非常奇特，下面的输出也是如此，尤其是在说明 Markdown 的代码围栏（```rust）时。

您必须显式请求 rust 代码块以获得 Rust 测试，使用 ```rust。这与 rustdoc 不同，rustdoc 假设代码块是 Rust。这样做的原因是，常见的 Markdown 解析器，如 GitHub 使用的解析器，默认情况下也不假设 Rust：您要么获得 Rust 语法高亮和测试，要么不获得 Rust 语法高亮和测试。

所以以下内容不会由 Skeptic 进行测试。

```

let this_is_not_going_to_be_compiled_and_run = @all;
It doesn't really matter what's in here.

```

为了指示Rust代码，代码块被标记为rust

```rust

println!("Calm your skepticism. This example is verified.");

```

Skeptic将解释代码块中的'info字符串'（应使用逗号分隔，,，以兼容GitHub）。这些单词会改变测试的解释方式：ignore、no_run和should_panic。

ignore 信息字符串

ignore信息字符串会导致测试完全被忽略。在测试期间，它不会被编译或运行。如果示例是用Rust编写的（并且您希望将其突出显示为Rust代码），但已知它是不完整的（因此不能直接编译），这很有用。

```rust,ignore

fn do_amazing_thing() -> i32 {
   // TODO: How do I do this?
   unimplemented! whatever I'm distracted, oh cookies!

```

no_run 信息字符串

no_run信息字符串会导致示例代码在测试期间不被运行。但标记为no_run的代码仍然会被编译。这对于具有副作用或依赖项的示例/测试很有用，这些副作用或依赖项在测试情况下是不希望的。

```rust,no_run

fn do_amazing_thing() -> i32 {
   // TODO: How do I do this?
   unimplemented!()
}

do_amazing_thing();

```

should_panic 信息字符串

should_panic会导致测试仅在它因为panic!()而终止时通过。

```rust,should_panic

assert!(1 == 100);

```

Skeptic模板

与rustdoc不同，Skeptic默认不会修改测试前的示例。Skeptic示例被放置在一个'.rs'文件中，然后编译并运行。

这意味着 - 默认情况下 - Skeptic示例需要main函数，如上面所有的示例所示。隐式包装示例在main中，以及通过模板自定义注入extern crate语句和crate属性。

文档的模板位于一个单独的文件中，该文件位于文件系统中文档旁边，并且具有与文档文件相同的完整名称，但附加一个".skt.md"模板。

例如，此文件README.md将其模板存储在README.md.skt.md中。

这种方案允许Markdown自然地由标准Markdown渲染器显示，而不显示模板本身。奇怪的文件扩展名也是这样，以便模板本身被解释为有效的Markdown。

考虑这个例子

let p = PathBuf::from("foo");
println!("{:?}", p);

此示例在没有定义main和导入PathBuf的情况下无法编译，但示例本身不包含这些样板代码。相反，它被标注为skt-foo，表示 skeptic模板foo，如下所示

```rust,skt-foo

let p = PathBuf::from("foo");
println!("{:?}", p);

```

这告诉skeptic在模板文件中查找具有相同skt-foo标注的另一个Markdown块，并使用禁用转义的Handlebars模板将它们组合在一起。以下是一个模板的例子（测试代码可用作test）

```rust,skt-foo

use std::path::PathBuf;

{{test}}

```

如果需要具有模块全局定义，如用于#[macro_use]crates的skeptic-root-template规范可以用来。

```rust,skeptic-root-template

#[macro_use]
extern crate serde_json;

```

旧式、文档全局模板

在文档中，带有rust代码块并标记为skeptic-template的将用作文档中所有示例的模板，这些示例没有明确标记。

```rust,skeptic-template

use std::path::PathBuf;

{{test}}

```

带有# 的Rustdoc样式不显示的行

类似于rustdoc，skeptic会在编译之前从任何代码行中移除前面的# 。在显示时隐藏此类行需要markdown渲染器的自定义支持。

许可证

MIT/Apache-2.0