Docs.rs scraped examples with dev dependencies

help
1

I'm trying to get docs.rs to scrape my crate's examples again - it worked once, but not since I added some dev dependencies...

The build log says

[INFO] [stderr] warning: Rustdoc did not scrape the following examples because they require dev-dependencies: flip, speed, clockwise_360, emergency_stop, wifi_wait_for_connection, take_off_and_land, remote_control, receive_video, show_video, move, drone_state
[INFO] [stderr]     If you want Rustdoc to scrape these examples, then add `doc-scrape-examples = true`
[INFO] [stderr]     to the [[example]] target configuration of at least one example.

(which is a bit wrong because that's all of them, but only a couple actually do, but that's another matter)

What exactly is the advice suggesting I do?

2

Due to Change rustdoc-scrape-examples to be a target-level configuration by willcrichton · Pull Request #10343 · rust-lang/cargo · GitHub, it basically tells you to explicitly include the doc-scrape-examples = true field in the example you want to scrape[1], i.e. you should write

# added in Cargo.toml
[[example]]
name = "name"
doc-scrape-examples = true

where name belongs to flip, speed, clockwise_360, emergency_stop, wifi_wait_for_connection, take_off_and_land, remote_control, receive_video, show_video, move, drone_state in your case.

Refer to cargo book: Unstable Features - The Cargo Book , especially

Note on dev-dependencies: documenting a library does not normally require the crate’s dev-dependencies. However, example targets require dev-deps. For backwards compatibility, -Z rustdoc-scrape-examples will not introduce a dev-deps requirement for cargo doc. Therefore examples will not be scraped from example targets under the following conditions:

  1. No target being documented requires dev-deps, AND
  2. At least one crate with targets being documented has dev-deps, AND
  3. The doc-scrape-examples parameter is unset or false for all [[example]] targets.

If you want examples to be scraped from example targets, then you must not satisfy one of the above conditions. For example, you can set doc-scrape-examples to true for one example target, and that signals to Cargo that you are ok with dev-deps being build for cargo doc.

Update: you mentioned docs.rs, so I guess you've already seen "How to use this feature" in Scraped examples - The rustdoc book .

  1. According to the last sentence in the following quote, you just need to specify doc-scrape-examples = true for an example only once. ↩︎

2 Likes
3

Thankyou! My tello-edu crate now has lovely scraped examples included in the docs.

This idea of automatically pulling in example code is a fantastic feature - I've not seen anything so helpful in any other language ecosystem. Well done to all involved! The Rust tooling really is a pleasure to use.

1 Like