cargo doc should render crate examples and link to them on main documentation page

[burtonageo]

(re-filing of rust-lang/rust#34022)

Cargo allows crate developers to create examples to show off their crate's API (as shown in http://doc.crates.io/guide.html#project-layout). These examples are very useful to see how the individual items in a crate can be used together, in a way that the standard documentation doesn't capture very well.

When viewing a crate's documentation, it would be useful if examples were rendered as standard source files, and there were links to view them on the main library overview page.

[japaric]

I have a shell script that I'm using in my f3 crate to do something like this but I'd really like to see something official implemented in Cargo and rustdoc.

For the interested: In my crate, this is a typical input example (examples/panic.rs); the scripts turns it into another .rs file and places it into the examples module (src/examples/panic.rs); and this is how the rendered output looks like.

[Dragonrun1]

So thought I'd bump this issue and see if there anyone looking at adding this IMHO very helpful feature.

[epage]

rust-lang/rust#88791 scrapes the examples and links to them from the API items used in the examples but it doesn't seem to provide a central list of all examples. @willcrichton did that idea ever come up?

[willcrichton]

We haven't talked about exactly that concept, but it's a great idea! FWIW, as a part of my scrape examples feature, rustdoc will now generate source files for scraped examples. So that infrastructure could be reused for this proposed feature.

One challenge to consider: a number of crates have examples, but these examples don't fall under the --examples filter. For instance, the gtk3-rs crate requires you to run examples via --bin. I think this is because Cargo doesn't allow examples to have standalone Cargo.toml configurations, but gtk3-rs needs that ability. So the simple implementation of this feature being "list out every file that matches the --examples filter" would not work for some crates.

The broader point: it might make sense for this feature to go hand-in-hand with a broader push to improve the examples directory. It's been kind of a second-class citizen of Cargo for a while.