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

[burtonageo]

(re-filing of https://github.com/rust-lang/rust/issues/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.