Merge pull request #239 from rustwasm/docs

Docs

.travis.yml

@@ -12,6 +12,15 @@ matrix:
     - cargo fmt --all -- --check
     env: RUST_BACKTRACE=1
 
+  # book
+  - rust: stable
+    before_script:
+    - (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update)
+    - (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.1" mdbook)
+    - cargo install-update -a
+    script:
+    - cd docs && mdbook build
+
   # dist linux binary
   - env: TARGET=x86_64-unknown-linux-musl DEPLOY=1
     rust: nightly
@@ -57,3 +66,11 @@ deploy:
     branch: master
     condition: $DEPLOY = 1
     tags: true
+
+  provider: pages
+  skip-cleanup: true
+  github-token: $GITHUB_TOKEN
+  local-dir: docs/book
+  keep-history: false
+  on:
+    branch: master

README.md

@@ -29,9 +29,8 @@ visiting that repo!
 
 ## 🎙️ Commands
 
-- [`init`](docs/init.md): [**Deprecated**] Initialize an npm wasm pkg from a rustwasm crate
-- [`build`](docs/build.md): Generate an npm wasm pkg from a rustwasm crate
 - [`init`](docs/init.md): Generate an npm wasm pkg from a rustwasm crate
+- [`build`](docs/build.md): Generate an npm wasm pkg from a rustwasm crate
 - [`pack` and `publish`](docs/pack-and-publish.md): Create a tarball of your rustwasm pkg and/or publish to a registry
 
 ## 📝 Logging

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["Ashley Williams"]
+multilingual = false
+src = "src"
+title = "Hello wasm-pack!"

docs/init.md

@@ -1,49 +0,0 @@
-# wasm-pack init(Deprecated)
-
-The `wasm-pack init` command creates the files neccessary for JavaScript
-interoperability and for publishing a package to npm. This involves
-generating a pkg folder. This pkg folder will contain the
-`README` and a `package.json` file.
-
-## Path
-
-The `wasm-pack init` command can be given an optional path argument, e.g.:
-
-```
-wasm-pack init examples/js-hello-world
-```
-
-This path should point to a directory that contains a `Cargo.toml` file. If no
-path is given, the `init` command will run in the current directory.
-
-## Target
-
-The init command accepts a `--target` argument. This will customize the output files
-to align with a particular type of JS module. This allows wasm-pack to generate either
-ES6 modules or CommonJS modules for use in browser and in NodeJS. Defaults to `browser`.
-The options are:
-
-```
-wasm-pack init --target nodejs
-```
-
-| Option    | Description                                                                                                     |
-|-----------|-----------------------------------------------------------------------------------------------------------------|
-| `nodejs`  | Outputs JS that uses CommonJS modules, for use with a `require` statement.                                      |
-| `browser` | Outputs JS that uses ES6 modules, primarily for use with `import` statements and/or bundlers such as `webpack`. |
-
-## Scope
-
-The init command also accepts an optional `--scope` argument. This will scope
-your package name, which is useful if your package name might conflict with
-something in the public registry. For example:
-
-```
-wasm-pack init examples/js-hello-world --scope test
-```
-
-This command would create a `package.json` file for a package called
-`@test/js-hello-world`. For more information about scoping, you can refer to
-the npm documentation [here][npm-scope-documentation].
-
-[npm-scope-documentation]: https://docs.npmjs.com/misc/scope

docs/prerequisites.md

@@ -1,29 +0,0 @@
-# Prerequisites
-
-## Rust and npm
-
-Before installing `wasm-pack`, you should make sure that you have already
-installed Rust and npm. You can confirm that these are installed using the
-following commands:
-
-```sh
-# Check if Rust is installed.
-cargo --version
-
-# Check if npm is installed.
-npm --version
-```
-
-You can find more information about installing Rust
-[here][rust-wasm-install-info] and more information about installing npm
-[here][npm-install-info].
-
-## Sign Up For npm
-
-You will need to create an npm account if you plan on publishing your package to
-the npm public registry. You can find information about signing up for npm
-[here][npm-signup-info].
-
-[rust-wasm-install-info]: https://rustwasm.github.io/book/setup.html
-[npm-install-info]: https://www.npmjs.com/get-npm
-[npm-signup-info]: https://www.npmjs.com/signup

docs/src/SUMMARY.md

@@ -0,0 +1,19 @@
+# Summary
+
+- [Prerequisites](./prerequisites/index.md)
+  - [Rust](./prerequisites/rust.md)
+  - [npm](./prerequisites/npm.md)
+- [Getting Started](./getting-started/index.md)
+  - [Installation](./getting-started/installation.md)
+  - [Project Setup](./getting-started/project-setup/index.md)
+    - [Using a Template](./getting-started/project-setup/using-a-template.md)
+    - [Manual Setup](./getting-started/project-setup/manual-setup.md)
+- [Commands](./commands/index.md)
+  - [`init` (DEPRECATED)](./commands/init.md)
+  - [`build`](./commands/build.md)
+  - [`pack` and `publish`](./command/pack-and-publish.md)
+- [Tutorial](./tutorial/index.md)
+  - [Writing a Rust-WebAssembly Library](./tutorial/writing-a-rust-webassembly-library.md)
+  - [Packaging and Publishing](./tutorial/packaging-and-publishing.md)
+  - [Using your Library](./tutorial/using-your-library.md)
+- [Contributing](./contributing.md)

docs/src/command/pack-and-publish.md

@@ -0,0 +1 @@
+# pack and publish

docs/src/commands/index.md

@@ -0,0 +1,11 @@
+# Commands
+
+`wasm-pack` has several commands to help you during the process of building
+a Rust-generated WebAssembly project.
+
+- `init`: This command has been deprecated in favor of `build`.
+- `build`: This command builds a `pkg` directory for you with compiled wasm and generated JS. [Learn more][build]
+- `pack` and `publish`: These command will create a tarball, and optionally publish it to a registry, such as npm. [Learn more][pack-pub]
+
+[build]: /commands/build.html
+[pack-pub]: /commands/pack-and-publish.html

docs/src/commands/init.md

@@ -0,0 +1,6 @@
+# wasm-pack init (DEPRECATED)
+
+This command has been deprecated in favor of `build`, which does the same thing, but is
+a much more representative name for the command. [Read the docs for `build`.][build]
+
+[build]: /commands/build.html

docs/src/commands/pack-and-publish.md

@@ -1,4 +1,4 @@
-# pack and publish 
+# pack and publish
 
 The `publish` and `pack` commands interact with the pkg directory that's 
 created when you run `wasm-pack init`. The `pack` command creates a tarball
@@ -29,4 +29,4 @@ $ wasm-pack pack myproject/src/
 Unable to find the pkg directory at path 'myproject/src/', or in a child directory of 'myproject/src/'
 ```
 
-If you don't set a path, they use the current directory as the path.
+If you don't set a path, they use the current directory as the path.

docs/src/getting-started/index.md

@@ -0,0 +1,7 @@
+# Getting Started
+
+In this section, we'll teach you how to get `wasm-pack` installed and how to setup a project
+to use `wasm-pack` with.
+
+- [Installation](/getting-started/installation.html)
+- [Project Setup](/getting-started/project-setup/index.html)

docs/src/getting-started/installation.md

@@ -0,0 +1,14 @@
+## Installation
+
+You can install `wasm-pack` using the following command:
+
+```
+cargo install wasm-pack
+```
+
+If you have already installed `wasm-pack` and want to install a newer version,
+you can use the `--force` option, like this:
+
+```
+cargo install wasm-pack --force
+```

docs/src/getting-started/project-setup/index.md

@@ -0,0 +1,8 @@
+# Project Setup
+
+There are a few things you need to do to setup a project for `wasm-pack`.
+We strongly recommending [using a template], but you can also set the project
+up [manually].
+
+[using a template]: /getting-started/project-setup/using-a-template.html
+[manually]: /getting-started/project-setup/manual-setup.html

docs/src/getting-started/project-setup/manual-setup.md

@@ -1,21 +1,4 @@
-# Setup
-
-## Installing wasm-pack
-
-You can install `wasm-pack` using the following command:
-
-```
-cargo install wasm-pack
-```
-
-If you have already installed `wasm-pack` and want to install a newer version,
-you can use the `--force` option, like this:
-
-```
-cargo install wasm-pack --force
-```
-
-## Project Initialization
+# Manual Setup
 
 You can create a new Rust project named `my-lib` using this command.
 
@@ -26,7 +9,7 @@ cargo new --lib my-lib
 The `--lib` flag specifies that the project is a library, which is important
 because we will be calling this code from JavaScript.
 
-### Cargo.toml changes
+#### Cargo.toml changes
 
 You will need to add `wasm-bindgen` to your `Cargo.toml` in the dependencies
 section. `wasm-bindgen` is a tool that facilitates interoperability between

docs/src/getting-started/project-setup/using-a-template.md

@@ -0,0 +1,20 @@
+# Using a Template
+
+You can create a new Rust-WebAssembly project by using the [rustwasm wasm-pack-template].
+
+To so do, you'll need the `cargo-generate` tool. To install `cargo-generate`:
+
+```
+cargo install cargo-generate
+```
+
+Then run:
+
+```
+cargo generate --git https://github.com/rustwasm/wasm-pack-template
+```
+
+You will be prompted to give your project a name. Once you do, you will have a directory
+with a new project, ready to go.
+
+[rustwasm wasm-pack-template]: https://github.com/rustwasm/wasm-pack-template

docs/src/prerequisites.md

@@ -0,0 +1 @@
+# Prerequisites

docs/src/prerequisites/index.md

@@ -0,0 +1,6 @@
+# Prerequisites
+
+To run `wasm-pack` you'll need to have both Rust and npm installed and configured.
+
+- [Rust](/prerequisites/rust.html)
+- [npm](/prerequisites/npm.html)

docs/src/prerequisites/npm.md

@@ -0,0 +1,20 @@
+# npm
+
+Currently, `wasm-pack` requires that you have npm installed to pack and publish your
+package. Longterm, this will be replaced by a Rust only version.
+
+If you would rather use another package manager that interfaces with the npm registry
+you may, however, the `pack` and `publish` commands depend on having npm installed.
+
+You can install [npm] by following [these instructions][npm-install-info].
+
+### npm Account
+
+Regardless of which package manager CLI tool you'l like to you, if you wish to publish
+your package to the npm registry, or another npm-like registry, you'll need an npm
+account.
+
+You can find information about signing up for npm [here][npm-signup-info].
+
+[npm-install-info]: https://www.npmjs.com/get-npm
+[npm-signup-info]: https://www.npmjs.com/signup

docs/src/prerequisites/rust.md

@@ -0,0 +1,31 @@
+# Rust
+
+`wasm-pack` is a tool written in Rust, and distributed with `cargo`. As a result,
+you'll need Rust and `cargo` to use `wasm-pack`.
+
+To install Rust, visit this [page](https://www.rust-lang.org/en-US/install.html).
+
+You can be sure you have Rust and Cargo installed by running:
+
+```
+rustc --version
+cargo --version
+```
+
+### `nightly` Rust
+
+`wasm-pack` depends on `wasm-bindgen` which currently requires Rust features that
+have not yet been stabilized. As a result, you'll need to use a nightly version of
+Rust to run `wasm-pack`.
+
+You can install the nightly channel by running:
+
+```
+rustup install nightly
+```
+
+You can configure rustup to always use `nightly` in a directory by running:
+
+```
+rustup override set nightly
+```

docs/src/setup.md

@@ -0,0 +1,78 @@
+# Setup
+
+## Installing wasm-pack
+
+You can install `wasm-pack` using the following command:
+
+```
+cargo install wasm-pack
+```
+
+If you have already installed `wasm-pack` and want to install a newer version,
+you can use the `--force` option, like this:
+
+```
+cargo install wasm-pack --force
+```
+
+## Project Initialization
+
+### Using a Template
+
+You can create a new Rust-WebAssembly project by using the [rustwasm wasm-pack-template].
+
+To so do, you'll need the `cargo-generate` tool. To install `cargo-generate`:
+
+```
+cargo install cargo-generate
+```
+
+Then run:
+
+```
+cargo generate --git https://github.com/rustwasm/wasm-pack-template
+```
+
+You will be prompted to give your project a name. Once you do, you will have a directory
+with a new project, ready to go.
+
+### Manually
+
+You can create a new Rust project named `my-lib` using this command.
+
+```
+cargo new --lib my-lib
+```
+
+The `--lib` flag specifies that the project is a library, which is important
+because we will be calling this code from JavaScript.
+
+#### Cargo.toml changes
+
+You will need to add `wasm-bindgen` to your `Cargo.toml` in the dependencies
+section. `wasm-bindgen` is a tool that facilitates interoperability between
+wasm modules and JavaScript.
+
+Next, add a `[lib]` section, with a new field named `crate-type` set to
+`"cdylib"`. This specifies that the library is a C compatible dynamic library,
+which helps `cargo` pass the correct flags to the Rust compiler when targeting
+`wasm32`.
+
+After making these changes, your `Cargo.toml` file should look something like
+this:
+
+```
+[package]
+name = "wasm-add"
+version = "0.1.0"
+authors = ["Michael Gattozzi <mgattozzi@gmail.com>"]
+description = "Code used to demonstrate how to use wasm-pack"
+license = "MIT/Apache-2.0"
+repository = "https://github.com/mgattozzi/wasm-add"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wasm-bindgen="0.2"
+```

docs/src/tutorial/index.md

@@ -0,0 +1,12 @@
+# Tutorial
+
+The goal of this tutorial is to introduce you to the `wasm-pack` workflow.
+
+This tutorial is aimed at folks who are both beginners to WebAssembly and Rust- you don't need
+much Rust knowledge to complete this tutorial.
+
+Be sure to have done the following before starting:
+
+1. Read and install all the [Prerequisites](/prerequisites.html).
+2. [Install `wasm-pack`](/getting-started/installation.html).
+3. [Setup a new project](/getting-started/project-setup/using-a-template.html).

docs/src/tutorial/packaging-and-publishing.md

@@ -0,0 +1,37 @@
+# Package Code for npm
+
+We've made our code so now we need to package it all up. In your project directory run the following
+command:
+
+```bash
+$ wasm-pack init --scope MYSCOPE
+```
+
+where `MYSCOPE` is your npm username. Normally you could just type `wasm-pack init` but since
+other people are doing this tutorial as well we don't want conflicts with the `wasm-add` package
+name! This command when run does a few things:
+
+1. It'll compile your code to wasm if you haven't already
+2. It'll generate a pkg folder with the wasm file, a JS wrapper file around the wasm, your README,
+   and a `package.json` file.
+
+This is everything you need to upload your code to npm! Let's do just that!
+
+First off you'll need to login to npm with the account you made earlier if you didn't already have
+one:
+
+```bash
+$ npm login
+```
+
+Next you'll need to go into the `pkg` directory and actually upload the package:
+
+```bash
+$ cd pkg
+$ npm publish --access=public
+```
+
+Now normally if things are not scoped you can just do `npm publish` but if you give it a scope
+you'll need to tell npm that this is actually public so it can publish it. We need to do that here
+since we gave our packages a scope to avoid conflicting with each other! Next up is actually running
+the code and verifying we got it from npm and how we can use that code.

docs/src/tutorial/using-your-library.md

@@ -0,0 +1,90 @@
+# Run The Code From npm
+
+Alright let's make a new small directory to test that we can now run this code and pull it from npm.
+
+```bash
+$ mkdir test
+$ cd test
+```
+
+Now we need to create a `package.json` file that looks like this:
+
+```json
+{
+  "scripts": {
+    "serve": "webpack-dev-server"
+  },
+  "dependencies": {
+    "@MYSCOPE/wasm-add": "^0.1.0"
+  },
+  "devDependencies": {
+    "webpack": "^4.0.1",
+    "webpack-cli": "^2.0.10",
+    "webpack-dev-server": "^3.1.0"
+  }
+}
+```
+
+where `MYSCOPE` is your npm username. You can expand this to be a more complete file but
+we're really just trying to verify that this works!
+
+Next up we'll need to create a small webpack configuration so that we can use the
+`webpack-dev-server` to serve the wasm file properly. It should be noted that webpack isn't
+a requirement. It's just what was chosen for this tutorial. You just need something to server the
+code! Here's what your `webpack.config.js` should look like:
+
+```javascript
+const path = require('path');
+module.exports = {
+  entry: "./index.js",
+  output: {
+    path: path.resolve(__dirname, "dist"),
+    filename: "index.js",
+  },
+  mode: "development"
+};
+```
+
+This tells webpack that if it's going to start things up use `index.js`. Before we do that though
+we'll need to setup a small html file. Create a new file called `index.html` and put this inside it:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>wasm-pack example</title>
+  </head>
+  <body>
+    <script src="./index.js"></script>
+  </body>
+</html>
+```
+
+We're almost set. Now we need to setup our JS file so that we can run some wasm code!
+Make a file called `index.js` and put this inside of it:
+
+```javascript
+const js = import("@MYSCOPE/wasm-add/wasm_add.js");
+js.then(js => {
+  js.alert_add(3,2);
+});
+```
+
+Since web pack [can't load wasm synchronously yet](https://github.com/webpack/webpack/issues/6615)
+we are using the import statement above followed
+by the promise in order to load it properly. This is what lets us then call `alert_add`. We're
+importing from the `node_module` folder we haven't gotten yet so let's import all of our
+dependencies finally and run the example!
+
+```bash
+$ npm install
+$ npm run serve
+```
+
+Then in a web browser navigate to `http://localhost:8080` you should see something like this:
+
+![An alert box saying "Hello from Rust! 3 + 2 = 5"](./wasm-pack/wasm-pack.png)
+
+If you did congrats you've successfully uploaded your first bit of wasm code to npm and used it
+properly!

docs/src/tutorial/writing-a-rust-webassembly-library.md

@@ -0,0 +1 @@
+# Writing a Rust-WebAssembly Library