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

[burtonageo]

(re-filing of #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]

#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.

[epage]

While originally examples were only a Cargo concept, with example-scraping, they are now a rustdoc concept. As this is about improving their rendering, I'm going to move this back to the rust repo.

Improving the handling of examples with their own Cargo.toml would need to be tracked as its own thing.