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

Question

我在机箱文档中有以下内容：

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

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

Answer 1

No。特性是由板条箱的最终用户选择的，您并不是唯一选择运行测试的人。如果你能做到你所要求的，你实际上会强迫任何想要运行测试的人下载并编译“可选的”依赖，使它不是非常可选的。

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

#![cfg_attr(feature = "alpha", doc = "
# Examples
```rust

fn alpha() {}

")]

同样，您也可以在一些文档中使用相反的情况，比如“请查看这个非常棒的特性！”

另请参阅：

• doc attribute documentation
• How would one achieve conditional compilation with Rust projects that have doctests?
• Generating documentation in macros

Answer 2

为了在编译项目的任何部分(包括测试)时始终具有依赖性，Development Dependencies是一个很好的选择。

[dev-dependencies]
stm32f103xx = "0.7.5"

正如你提到的，板条箱也是一个可选的主依赖项，你可以将它保留在你的清单中。

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