Filling out missing Introductory Documentation

[alexcrichton]

I'd like to use this issue as a tracking issue for filling out gaps in wasmtime's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)

Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!

Book Documentation

As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!

• Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the wasmtime CLI to execute a Rust-generated WebAssembly file - @NoCulture
• List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
• Documenation of using wasm from Python - @jjsullivan5196
• Documentation of using wasm from .NET
• Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
• Documentation of using wasm from bash (aka examples of using the CLI)
• Writing WebAssembly from C/C++
• Writing WebAssembly, markdown example - @humancalico
• Embedding wasmtime overview
• Embedding wasmtime in Rust - currently has docs but feels a bit light on content
• Embedding wasmtime in C/C++
• Embedding wasmtime in .NET - probably want a page on this?
• What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
• Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
• Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
• Security policy
• Disclosure policy
• Sandboxing - @sunfishcode
• Governance

API Documentation

• The crate documentation feels lacking and could use a broad example to introduce the crate.
• The Module type should have at least one example somewhere.
• The Instance type should have at least one example.
• The Store type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.
• The Memory type needs examples of safe usage, and double-checks on wording about unsafe usage.
• The Func type could use an example on the get family of methods.
• Types which correspond to the wasm specification should link there where possible.

Examples

I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:

• Move Rust examples to a top-level examples directory - @alexcrichton
• Move C examples to the top-level examples directory too - @alexcrichton
• Every example has a comment at the top of the file of how to build and run it - @alexcrichton
  • Rust is typically cargo run --example foo
  • C is gcc examples/foo.c -I crates/c-api/include -o foo && ./foo (ish)
• Wasm files are never checked in for examples - @alexcrichton
  • Either wasm is written inline as a *.wat string
  • Or example is structured as examples/name/main.rs with a corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/name/wasm.c if we want to show off a C-compiled wasm example)
• Every example is available in both Rust and C - @alexcrichton
  • For examples/foo.rs we have a corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/foo/main.c
• Example showing how to link in the WASI functions
• Example of reading a string from a wasm module
• Example of a string processor, for example a markdown renderer
• All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton

[ifennna]

I could take a stab at this: "Step-by-step tutorial to create and run hello-world.wasm"

[alexcrichton]

I'm working on a number of the examples bullets, mostly around organizing them and bringing C on par with Rust. Also CI!

[sunfishcode]

I'll write some content for the Sandboxing section.

[jjsullivan5196]

I can work on getting the python examples illustrated in the documentation. I think the demo video on the wasmtime home page is pretty comprehensive, so I'll probably just add some more details for project setup with pipenv and the like https://youtu.be/Qn_4F3foB3Q @alexcrichton do you think this is a good approach?

Also just saw #677, do you think I can still document the python support as of v0.12.0, or should I wait until interface types are more stable? The issue makes it seem like the interface shouldn't change much for module users.

[alexcrichton]

@jjsullivan5196 sounds great to me! I do think we should still at least document what we have which should work well for integers and such, but yeah the exact video won't work any more because strings are no longer supported.

[akshatagarwl]

@alexcrichton I'll write the markdown parser for the book