How to show run button in rust crate doc example?

I'm publishing my first crate along with its own docs, and i need to showcase some example code, but, how to add a run button on docs right side.

Here is my cargo doc code

//! ## Declare a closure
    //!  closure can be declared with the following examples
    //! ## Examples
    //! ```
    //!  let first_closure = || 10;
    //!  println!("The first closure : {:?}", first_closure());
    //! ```

You have to set the html_playground_url at the crate level for run buttons to show up. I.e. adding a line #![doc(html_playground_url = "https://play.rust-lang.org")] at the top of your lib.rs file should add the run buttons to your examples.

2 Likes

Note that the url for html_playground_url needs to point to a playground that can run your doctests. As mentioned in Unstable features - The rustdoc book (rust-lang.org) the official playground doesn't include every crate. In fact, it is limited to only a handful of popular crates: Rust Playground

Also, the run button in rustdoc doesn't integrate the run results as an iframe within the documentation page. It's literally just a button that opens the URL in a new window with the example code appended.

2 Likes

Im using cargo workspace. Is there any alternative way, where i can define that in workspace Cargo.toml file and reflect that run button on entire workspace example codes.

You could add a .cargo/config.toml to your project with the following content:

[build]
rustdocflags = [ "-Z", "unstable-options", "--playground-url", "https://play.rust-lang.org" ]

That will tell Cargo to run rustdoc with the unstable --playground-url flag, which has the same behaviour as adding #![doc(html_playground_url = "https://play.rust-lang.org")] to the crate you are building.


When you are building for docs.rs you can create a metadata table in your Cargo.toml file with arguments parsed by docs.rs:

[package.metadata.docs.rs]
rustdoc-args = [ "-Z", "unstable-options", "--playground-url", "https://play.rust-lang.org" ]

This won't work for local builds as the .cargo/config.toml option I presented above does though. And AFAIK you have to add the metadata table to each of your workspace's packages.

2 Likes

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.