[rustdoc] Rustdoc should render crate examples and link to them on main documentation page

[burtonageo]

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.

[steveklabnik]

Related to, but not the same as, #16103 rust-lang/cargo#739

[steveklabnik]

Ah, this was filed in the rust repo, not the cargo repo. @burtonageo mind re-filing https://github.com/rust-lang/cargo/issues/new thanks!

[steveklabnik]

(Specifically, because "examples" are a Cargo feature, not a Rust feature)

[burtonageo]

@steveklabnik Done, thanks