diff --git a/.gitignore b/.gitignore index 7585238efe..e82f879ba9 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ book + +# Auto-generated files from macOS +.DS_Store \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3e3e0aa319..7e00336d6b 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -213,3 +213,4 @@ - [Meta](meta.md) - [Documentation](meta/doc.md) + - [Playpen](meta/playpen.md) diff --git a/src/meta.md b/src/meta.md index f5119d5f41..a7434521c7 100644 --- a/src/meta.md +++ b/src/meta.md @@ -4,9 +4,9 @@ Some topics aren't exactly relevant to how you program but provide you tooling or infrastructure support which just makes things better for everyone. These topics include: -* Documentation: Generate library documentation for users via the included -`rustdoc`. -* Testing: Create testsuites for libraries to give confidence that your -library does exactly what it's supposed to. -* Benchmarking: Create benchmarks for functionality to be confident that -they run quickly. +- [Documentation][doc]: Generate library documentation for users via the included + `rustdoc`. +- [Playpen][playpen]: Integrate the Rust Playpen(also known as the Rust Playground) in your documentation. + +[doc]: meta/doc.md +[playpen]: meta/playpen.md diff --git a/src/meta/playpen.md b/src/meta/playpen.md new file mode 100644 index 0000000000..e8706752cc --- /dev/null +++ b/src/meta/playpen.md @@ -0,0 +1,38 @@ +# Playpen + +The [Rust Playpen](https://github.com/rust-lang/rust-playpen) is a way to experiment with Rust code through a web interface. This project is now commonly referred to as [Rust Playground](https://play.rust-lang.org/). + +## Using it with `mdbook` + +In [`mdbook`][mdbook], you can make code examples playable and editable. + +```rust,editable +fn main() { + println!("Hello World!"); +} +``` + +This allows the reader to both run your code sample, but also modify and tweak it. The key here is the adding the word `editable` to your codefence block separated by a comma. + +````markdown +```rust,editable +//...place your code here +``` +```` + +## Using it with docs + +You may have noticed in some of the [official Rust docs][official-rust-docs] a button that says "Run", which opens the code sample up in a new tab in Rust Playground. This feature is enabled if you use the #[doc] attribute called [`html_playground_url`][html-playground-url]. + +### See also: + +- [The Rust Playground][rust-playground] +- [The next-gen playpen][next-gen-playpen] +- [The rustdoc Book][rustdoc-book] + +[rust-playground]: https://play.rust-lang.org/ +[next-gen-playpen]: https://github.com/integer32llc/rust-playground/ +[mdbook]: https://github.com/rust-lang/mdBook +[official-rust-docs]: https://doc.rust-lang.org/core/ +[rustdoc-book]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html +[html-playground-url]: https://doc.rust-lang.org/rustdoc/the-doc-attribute.html#html_playground_url