Should rustdoc include cargo examples?

1

I am referring to the examples that come from examples/ directory of a crate in the default configuration, or whatever is specified as [[example]] in the Cargo.toml.

When I use a crate dependency, I will generally look at its documentation on docs.rs. I am not in the habit of going into the source repository, especially since the docs.rs page usually includes its own copy of the source code. However I realized today that the rustdocs do not include examples so the source repository is the only place to see the examples. Anything that a crate author puts in [[example]] instead of [[bin]] or [[test]] is probably intended to serve as documentation in some way, so would it make sense for rustdoc to package up the source code of all examples and include them in the docs?

1 Like
2

This is already implemented in rustdoc, but not yet stabilised.

https://doc.rust-lang.org/rustdoc/scraped-examples.html#scraped-examples

You can use it with the following command:

cargo doc -Zunstable-options -Zrustdoc-scrape-examples
3 Likes
3

just want to mention, it is supported on https://docs.rs too! this is a really useful documenting feature. I hope more crates will utilize this feature. to enable this feature on docs.rs, you add the following metadata section to your Cargo.toml manifest:

[package.metadata.docs.rs]
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]

here's an example how it looks on docs.rs:

4 Likes
4

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.