rust - 有没有办法仅在 rustdoc 验证示例时启用 Cargo 功能？

Question

我在 crate 文档中有以下内容：

//! # Examples
//! ```rust,no_run
//! extern crate stm32f103xx;
//! // ...
//! ```

问题是对stm32f103xxcrate 的依赖是可选的。如果我默认启用功能stm32f103xx，一切正常，但我不想将其设为默认。有没有办法仅在rustdoc验证示例时启用该功能？

Answer 1

没有。功能由 crate 的最终用户选择，并且您不是唯一选择运行测试的人。如果您可以按照您的要求进行操作，那么您实际上会强制任何想要运行测试的人下载并编译“可选”依赖项，从而使其不是很可选。

---

相反，您可以做的是仅在启用该功能时包含该文档。这并不明显，但文档注释被转换为属性语法 ( #[doc = "..."])。结合cfg_attr，您可以有条件地包含文档，从而有条件地编译并运行一个示例：

#![cfg_attr(feature = "alpha", doc = "
# Examples
```rust
fn alpha() {}
```
")]

同样，对于一些说明“检查这个很棒的功能！”的文档，您可以有相反的情况。

也可以看看：

• doc 属性文档
• 如何使用具有 doctest 的 Rust 项目实现条件编译？
• 在宏中生成文档

Answer 2

为了在编译项目的任何部分（包括诸如此类的测试）时始终具有依赖关系，开发依赖关系非常适合。

[dev-dependencies]
stm32f103xx = "0.7.5"

正如您提到的，板条箱作为主要依赖项也是可选的，您可以将其保留在清单中。

[dependencies]
stm32f103xx = { version = "0.7.5", optional = true }