Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
burtonageo opened this issue Jun 1, 2016 · 1 comment

Comments

Projects
None yet
3 participants
@burtonageo
Copy link
Contributor

commented Jun 1, 2016

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

@burtonageo burtonageo changed the title [rustdoc] Rustdoc should render crate examples and link to them on main documentation page cargo doc should render crate examples and link to them on main documentation page Jun 1, 2016

@japaric

This comment has been minimized.

Copy link
Member

commented Oct 6, 2016

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.