抓取示例

Rustdoc 具有一个不稳定功能，它可以自动从 Cargo 工作区的 examples/ 目录中抓取正在记录的项目的示例。这些示例将包含在为该项目生成的文档中。例如，如果您的库包含一个公共函数

// a_crate/src/lib.rs
pub fn a_func() {}

并且您有一个调用此函数的示例

// a_crate/examples/ex.rs
fn main() {
  a_crate::a_func();
}

那么此代码片段将包含在 a_func 的文档中。此文档由 Rustdoc 插入，无法由箱子作者手动编辑。

如何使用此功能

此功能不稳定，因此您可以通过使用不稳定的 rustdoc-scrape-examples 标志调用 Rustdoc 来启用它

cargo doc -Zunstable-options -Zrustdoc-scrape-examples

要在 docs.rs 上启用此功能，请将此添加到您的 Cargo.toml

[package.metadata.docs.rs]
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]

工作原理

当您运行 cargo doc 时，Rustdoc 将分析所有与 Cargo 的 --examples 过滤器匹配的箱子，以查找正在记录的项目的实例。然后 Rustdoc 将在生成的文档中包含这些实例的源代码。

Rustdoc 采用了一些技术来确保这些示例不会淹没文档阅读者，并且不会使页面大小膨胀

  1. 对于给定的项目，页面中最多包含 5 个示例。其余示例只是指向源代码的链接。
  2. 默认情况下只显示一个示例，其余示例隐藏在切换按钮后面。
  3. 对于包含示例的给定文件，只有包含示例的项目将包含在生成的文档中。

对于给定的项目，Rustdoc 根据示例的大小对其示例进行排序 - 较小的示例首先显示。

常见问题解答

我的示例没有显示在文档中

此功能使用 Cargo 的查找示例约定。您应该确保 cargo check --examples 包含您的示例文件。