Merge pull request #980 from alexcrichton/mdbook-test

Test book documentation on CI

.github/workflows/main.yml

@@ -25,11 +25,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v1
+      with:
+        submodules: true
     - run: |
         set -e
         curl -L https://github.com/rust-lang-nursery/mdBook/releases/download/v0.3.1/mdbook-v0.3.1-x86_64-unknown-linux-gnu.tar.gz | tar xzf -
         echo ::add-path::`pwd`
     - run: (cd docs && mdbook build)
+    - run: cargo build -p wasmtime
+    - run: (cd docs && mdbook test -L ../target/debug/deps)
     - uses: actions/upload-artifact@v1
       with:
         name: doc-book

docs/cli-cache.md

@@ -2,7 +2,7 @@
 
 The configuration file uses the [toml] format.
 You can create a configuration file at the default location with:
-```
+```sh
 $ wasmtime config new
 ```
 It will print the location regardless of the success.

docs/embed-rust.md

@@ -18,7 +18,7 @@ Let's create a simple WebAssembly file with a single exported function that retu
 
 # Create rust project
 
-```
+```sh
 $ cargo new --bin wasmtime_hello
 $ cd wasmtime_hello
 $ cp $WASM_FILES/hello.wasm .
@@ -26,7 +26,7 @@ $ cp $WASM_FILES/hello.wasm .
 
 We will be using the wasmtime engine/API to run the wasm file, so we will add the dependency to `Cargo.toml`:
 
-```
+```toml
 [dependencies]
 wasmtime = "<current version>"
 ```
@@ -36,6 +36,7 @@ where "<current version>" is the current version number of the `wasmtime` crate.
 It is time to add code to the `src/main.rs`. First, storage needs to be activated:
 
 ```rust
+# extern crate wasmtime;
 use wasmtime::*;
 
 let store = Store::default();
@@ -43,18 +44,32 @@ let store = Store::default();
 
 The `hello.wasm` can be read from the file system and provided to the `Module` object constructor as `&[u8]`:
 
-```rust
+```rust,no_run
+# extern crate wasmtime;
+# use wasmtime::*;
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+# let store = Store::default();
 use std::fs::read;
 
-let hello_wasm = read("hello.wasm").expect("wasm file");
+let hello_wasm = read("hello.wasm")?;
 
-let module = Module::new(&store, &hello_wasm).expect("wasm module");
+let module = Module::new(&store, &hello_wasm)?;
+# Ok(())
+# }
 ```
 
-The module instance can now be created. Normally, you would provide exports, but in this case, there are none required:
+The module instance can now be created. Normally, you would provide imports, but
+in this case, there are none required:
 
 ```rust
-let instance = Instance::new(&module, &[]).expect("wasm instance");
+# extern crate wasmtime;
+# use wasmtime::*;
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+# let store = Store::default();
+# let module = Module::new(&store, "(module)")?;
+let instance = Instance::new(&module, &[])?;
+# Ok(())
+# }
 ```
 
 Everything is set. If a WebAssembly module has a start function -- it was run.
@@ -62,34 +77,74 @@ The instance's exports can be used at this point. wasmtime provides functions
 to get an export by name, and ensure that it's a function:
 
 ```rust
+# extern crate wasmtime;
+# use wasmtime::*;
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+# let store = Store::default();
+# let module = Module::new(&store, r#"(module (func (export "answer")))"#)?;
+# let instance = Instance::new(&module, &[])?;
 let answer = instance.get_export("answer").expect("answer").func().expect("function");
+# Ok(())
+# }
 ```
 
-The exported function can be called using the `call` method. The exported "answer" function accepts no parameters and returns a single `i32` value.
+The exported function can be called using the `call` method. The exported
+"answer" function accepts no parameters and returns a single `i32` value.
 
 ```rust
-let result = answer.call(&[]).expect("success");
+# extern crate wasmtime;
+# use wasmtime::*;
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+# let store = Store::default();
+# let module = Module::new(&store, r#"(module (func (export "answer") (result i32) i32.const 2))"#)?;
+# let instance = Instance::new(&module, &[])?;
+# let answer = instance.get_export("answer").expect("answer").func().expect("function");
+let result = answer.call(&[])?;
 println!("Answer: {:?}", result[0].i32());
+# Ok(())
+# }
+```
+
+Since we know the signature of the function ahead of time, we can also assert
+its signature and call the function directly without doing conversions:
+
+```rust
+# extern crate wasmtime;
+# use wasmtime::*;
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+# let store = Store::default();
+# let module = Module::new(&store, r#"(module (func (export "answer") (result i32) i32.const 2))"#)?;
+# let instance = Instance::new(&module, &[])?;
+# let answer = instance.get_export("answer").expect("answer").func().expect("function");
+let answer = answer.get0::<i32>()?;
+let result: i32 = answer()?;
+println!("Answer: {}", result);
+# Ok(())
+# }
 ```
 
-The names of the WebAssembly module's imports and exports can be discovered by means of module's corresponding methods.
+The names of the WebAssembly module's imports and exports can be discovered by
+means of module's corresponding methods.
 
 # src/main.rs
 
-```rust
+```rust,no_run
+# extern crate wasmtime;
+use std::error::Error;
 use std::fs::read;
 use wasmtime::*;
 
-fn main() {
+fn main() -> Result<(), Box<dyn Error>> {
     let store = Store::default();
 
-    let wasm = read("hello.wasm").expect("wasm file");
+    let wasm = read("hello.wasm")?;
 
-    let module = Module::new(&store, &wasm).expect("wasm module");
-    let instance = Instance::new(&module, &[]).expect("wasm instance");
+    let module = Module::new(&store, &wasm)?;
+    let instance = Instance::new(&module, &[])?;
 
     let answer = instance.get_export("answer").expect("answer").func().expect("function");
-    let result = answer.call(&[]).expect("success");
+    let result = answer.call(&[])?;
     println!("Answer: {:?}", result[0].i32());
+    Ok(())
 }
 ```

docs/wasm-rust.md

@@ -164,7 +164,7 @@ wasm-bindgen = "0.2.54"
 
 Using this crate, we can then update our `src/lib.rs` with the following:
 
-```rust
+```rust,ignore
 use wasm_bindgen::prelude::*;
 
 #[wasm_bindgen]
@@ -248,6 +248,7 @@ Only functions can be imported in Rust at this time, and they can be imported
 via raw interfaces like:
 
 ```rust
+# struct MyStruct;
 #[link(wasm_import_module = "the-wasm-import-module")]
 extern "C" {
     // imports the name `foo` from `the-wasm-import-module`
@@ -270,7 +271,7 @@ extern "C" {
 
 When you're using `wasm-bindgen` you would instead use:
 
-```rust
+```rust,ignore
 use wasm_bindgen::prelude::*;
 
 #[wasm_bindgen(module = "the-wasm-import-module")]