Is there a way to enable a Cargo feature only when rustdoc verifies examples?

user_31118 0
Viewed 1086

I have the following piece in the crate documentation:

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

The problem is that the dependency on stm32f103xx crate is optional. Everything works fine if I enable feature stm32f103xx by default, but I don't want to make it default. Is there any way to enable that feature only when rustdoc verifies examples?

rustdoc rust
2 Answers

No. Features are chosen by the end user of the crate, and you aren't the only person who chooses to run the tests. If you could do what you are asking, you'd actually force anyone who wanted to run the tests to download and compile the "optional" dependency, making it not very optional.

What you can do instead is only include that piece of the documentation when the feature is enabled. It's not obvious, but documentation comments are transformed into the attribute syntax (#[doc = "..."]). Combined with cfg_attr, you can conditionally include documentation, thus conditionally compile and run an example:

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

Likewise, you can have the opposite case for a bit of documentation that says "check out this awesome feature!".

See also:

user_1554230

In order to always have a dependency when compiling any parts of the project (including tests such as that one), Development Dependencies are a good fit.

[dev-dependencies]
stm32f103xx = "0.7.5"

As you mention that the crate is also optional as a main dependency, you can keep it as so in your manifest.

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