3

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?

Shepmaster
  • 388,571
  • 95
  • 1,107
  • 1,366
Ivan Dubrov
  • 4,778
  • 2
  • 29
  • 41
  • Are you saying that the inline example should only be compiled when a feature is enabled? Or that you don't want the dependency to "live" in the main crate unless for building that example? – E_net4 Sep 20 '17 at 20:44
  • @E_net4 I want the dependency in the main crate, but only optional (to be enabled by the crate users). At the same time, the example I give in the documentation assumes that this dependency is enabled. – Ivan Dubrov Sep 20 '17 at 20:57

2 Answers2

4

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:

Stargateur
  • 24,473
  • 8
  • 65
  • 91
Shepmaster
  • 388,571
  • 95
  • 1,107
  • 1,366
  • I don't quite understand. Why building documentation would require that dependency? I would think that only verifying that examples are sound (running doctests) would require it. – Ivan Dubrov Sep 20 '17 at 21:38
  • @IvanDubrov haha, good point. I mis-stated in the first paragraph (for whatever reason, `cargo doc` is the thing that runs the doc tests in my head), but I think the rest of my point is still valid. – Shepmaster Sep 20 '17 at 21:42
  • The answer is related to the another topic - enabling docs when a feature is enabled. Thank google I have found it, but I think we should do something to let other people find this answer easily: the question title and description don't ask specifically for this. – VP. Jun 01 '19 at 08:09
1

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 }
E_net4
  • 27,810
  • 13
  • 101
  • 139
  • Doesn't quite work since certain pieces of my library are only enabled when "stm32f103xx" feature is present (so, example would not compile, but for a different reason :) ). Making a dependency non-optional does not turn on the feature. P.S. I guess I'm trying to bee too smart... I think, I will simply run "cargo test' with that feature enabled and be done with that. :) – Ivan Dubrov Sep 20 '17 at 21:49