From bdc6bca58bc78a55f0b86cc8fcda75ed9a4a6b91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Ram=C3=B3n=20Jim=C3=A9nez?= Date: Fri, 22 Mar 2024 20:06:01 +0100 Subject: [PATCH] Add `book` example --- README.md | 8 +- book/.gitignore | 3 + book/book.toml | 9 ++ book/src/SUMMARY.md | 3 + {assets => book/src/assets}/example.gif | Bin {assets => book/src/assets}/logo.svg | 0 book/src/guide.md | 152 ++++++++++++++++++++++++ 7 files changed, 172 insertions(+), 3 deletions(-) create mode 100644 book/.gitignore create mode 100644 book/book.toml create mode 100644 book/src/SUMMARY.md rename {assets => book/src/assets}/example.gif (100%) rename {assets => book/src/assets}/logo.svg (100%) create mode 100644 book/src/guide.md diff --git a/README.md b/README.md index b28b7cb..a52f309 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
- + # mdbook-iced @@ -14,7 +14,7 @@ An mdBook preprocessor to turn [iced] code blocks into interactive examples. -An interactive example +An interactive example
@@ -23,7 +23,7 @@ This is a simple mdBook preprocessor that can add a play button to any [iced] co Pressing the play button loads and embeds the resulting Wasm application in a fully interactive `` right under the code block. -It is compatible with any code block that features a `main` function where an [iced] program is run—even if it is commented! This means +It is compatible with any code block that features a `main` function where an [iced] program is run—even if it is hidden! This means it can be used to create interactive examples even for books completely unrelated to [iced]. Currently, this preprocessor is mainly being used in [the official guide] to [iced]. Check it out! @@ -91,6 +91,8 @@ fn view(value: &u64) -> Column { You can control the height of the embedded application by using `iced(height=)` as a label (e.g. `iced(height=100px)`). +Check out the [`book`](book) directory for a real mdBook example! + [iced]: https://github.com/iced-rs/iced [`wasm-bindgen-cli`]: https://rustwasm.github.io/wasm-bindgen/reference/cli.html [the official guide]: https://book.iced.rs/ diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 0000000..02b1974 --- /dev/null +++ b/book/.gitignore @@ -0,0 +1,3 @@ +book +target +.icebergs diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 0000000..6ea7e7f --- /dev/null +++ b/book/book.toml @@ -0,0 +1,9 @@ +[book] +authors = ["Héctor Ramón Jiménez"] +language = "en" +multilingual = false +src = "src" +title = "mdbook-iced" + +[preprocessor.iced] +rev = "441e9237cd1c9c9b61d9b144b5b4dafa236ace28" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 0000000..7060be6 --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,3 @@ +# Summary + +- [Guide](./guide.md) diff --git a/assets/example.gif b/book/src/assets/example.gif similarity index 100% rename from assets/example.gif rename to book/src/assets/example.gif diff --git a/assets/logo.svg b/book/src/assets/logo.svg similarity index 100% rename from assets/logo.svg rename to book/src/assets/logo.svg diff --git a/book/src/guide.md b/book/src/guide.md new file mode 100644 index 0000000..45b0a63 --- /dev/null +++ b/book/src/guide.md @@ -0,0 +1,152 @@ +
+ + + +# mdbook-iced + +[![Documentation](https://docs.rs/mdbook-iced/badge.svg)](https://docs.rs/mdbook-iced) +[![Crates.io](https://img.shields.io/crates/v/mdbook-iced.svg)](https://crates.io/crates/mdbook-iced) +[![License](https://img.shields.io/crates/l/mdbook-iced.svg)](https://github.com/iced-rs/mdbook-iced/blob/master/LICENSE) +[![Downloads](https://img.shields.io/crates/d/mdbook-iced.svg)](https://crates.io/crates/mdbook-iced) +[![Test Status](https://img.shields.io/github/actions/workflow/status/iced-rs/mdbook-iced/test.yml?branch=master&event=push&label=test)](https://github.com/iced-rs/mdbook-iced/actions) +[![Discourse](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscourse.iced.rs%2Fsite%2Fstatistics.json&query=%24.users_count&suffix=%20users&label=discourse&color=5e7ce2)](https://discourse.iced.rs/) +[![Discord Server](https://img.shields.io/discord/628993209984614400?label=&labelColor=6A7EC2&logo=discord&logoColor=ffffff&color=7389D8)](https://discord.gg/3xZJ65GAhd) + +An mdBook preprocessor to turn [iced] code blocks into interactive examples. + +An interactive example + +
+ +## Overview +This is a simple mdBook preprocessor that can add a play button to any [iced] code block. + +Pressing the play button loads and embeds the resulting Wasm application in a fully interactive `` right under the code block. + +It is compatible with any code block that features a `main` function where an [iced] program is run—even if it is hidden! This means +it can be used to create interactive examples even for books completely unrelated to [iced]. + +Currently, this preprocessor is mainly being used in [the official guide] to [iced]. Check it out! + +## Installation +Install the `mdbook-iced` preprocessor and the [`wasm-bindgen-cli`] tool with `cargo install`: + +``` +cargo install mdbook-iced wasm-bindgen-cli +``` + +Also, make sure your toolchain has the `wasm32-unknown-unknown` target: + +``` +rustup target add wasm32-unknown-unknown +``` + +## Usage +Add a `[preprocessor.iced]` entry to your `book.toml` and specify the revision of `iced` your book will use: + +```toml +[preprocessor.iced] +# You can use a commit hash +rev = "9db6ac8f202ebdc1453edee01da0b30aee0949d8" +# ... a branch +branch = "master" +# ... or a tag! +tag = "0.13.0" # Not yet released! +``` + +Then, simply add an `iced` label to any executable code block you want to make playable. For instance, the +classical counter: + +````markdown +# A cool example + +This is an mdBook and here is an iced counter: + +```rust,ignore,iced +# use iced::widget::{button, column, text, Column}; +# +pub fn main() -> iced::Result { + iced::run("A counter", update, view) +} +# +# #[derive(Debug, Clone)] +# enum Message { +# Increment, +# } +# +# fn update(value: &mut u64, message: Message) { +# match message { +# Message::Increment => *value += 1, +# } +# } +# +# fn view(value: &u64) -> Column { +# column![ +# text(value), +# button("+").on_press(Message::Increment), +# ] +# } +``` +```` + +This produces the following code block: + +```rust,ignore,iced +# use iced::widget::{button, column, text, Column}; +# +pub fn main() -> iced::Result { + iced::run("A counter", update, view) +} +# +# #[derive(Debug, Clone)] +# enum Message { +# Increment, +# } +# +# fn update(value: &mut u64, message: Message) { +# match message { +# Message::Increment => *value += 1, +# } +# } +# +# fn view(value: &u64) -> Column { +# column![ +# text(value), +# button("+").on_press(Message::Increment), +# ] +# } +``` + +You can control the height of the embedded application by using `iced(height=)` as a label (e.g. `iced(height=100px)`). +For instance: + +```rust,ignore,iced(height=100px) +# use iced::widget::{button, column, text, Column}; +# +pub fn main() -> iced::Result { + iced::run("A counter", update, view) +} +# +# #[derive(Debug, Clone)] +# enum Message { +# Decrement, +# } +# +# fn update(value: &mut u64, message: Message) { +# match message { +# Message::Decrement => *value -= 1, +# } +# } +# +# fn view(value: &u64) -> Column { +# column![ +# text(value), +# button("-").on_press(Message::Decrement), +# ] +# } +``` + +[iced]: https://github.com/iced-rs/iced +[`wasm-bindgen-cli`]: https://rustwasm.github.io/wasm-bindgen/reference/cli.html +[the official guide]: https://book.iced.rs/ +