Merge pull request #612 from rustwasm/fix-docs-srsly

fix the docs

.travis.yml

@@ -62,6 +62,7 @@ matrix:
     - (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.2" mdbook)
     - cargo install-update -a
     script:
+    - mdbook --version
     - (cd docs && mv _theme theme && mdbook build)
     - rustc ./docs/_installer/build-installer.rs
     - ./build-installer

docs/src/SUMMARY.md

@@ -1,5 +1,6 @@
 # Summary
 
+- [Introduction](./introduction.md)
 - [Prerequisites](./prerequisites/index.md)
   - [npm (optional)](./prerequisites/npm.md)
   - [Non-`rustup` setups](./prerequisites/non-rustup-setups.md)

docs/src/introduction.md

@@ -0,0 +1,21 @@
+![wasm ferris](https://rustwasm.github.io/wasm-pack/public/img/wasm-ferris.png)
+
+<h1 style="text-align: center;">Welcome to the <code>wasm-pack</code> docs!</h1>
+
+This tool seeks to be a one-stop shop for building and working with rust-
+generated WebAssembly that you would like to interop with JavaScript, in the
+browser or with Node.js. `wasm-pack` helps you build rust-generated
+WebAssembly packages that you could publish to the npm registry, or otherwise use
+alongside any javascript packages in workflows that you already use, such as [webpack]
+or [greenkeeper].
+
+[bundler-support]: https://github.com/rustwasm/team/blob/master/goals/bundler-integration.md#details
+[webpack]: https://webpack.js.org/
+[greenkeeper]: https://greenkeeper.io/
+
+This project is a part of the [rust-wasm] group. You can find more info by
+visiting that repo!
+
+[rust-wasm]: https://github.com/rustwasm/team
+
+![demo](https://github.com/rustwasm/wasm-pack/raw/master/demo.gif)

docs/src/prerequisites/index.md

@@ -18,4 +18,4 @@ involved!
 
 [npm]: prerequisites/npm.html
 
-Using a non-rustup setup? Learn how to configure it for wasm-pack [here](./non-rustup-setups.html).
+Using a non-rustup setup? Learn how to configure it for wasm-pack [here](prerequisites/non-rustup-setups.html).

docs/src/prerequisites/npm.md

@@ -20,11 +20,6 @@ your package to the npm registry you'll need an npm account.
 
 You can find information about signing up for npm [here][npm-signup-info].
 
-If you'd rather not sign up for an account or publish a package to the regsitry, you can
-use the [`npm link`] command to use your generated package locally, which we'll discuss
-later in the [Tutorial].
-
 [`npm link`]: https://docs.npmjs.com/cli/link
 [npm-install-info]: https://www.npmjs.com/get-npm
 [npm-signup-info]: https://www.npmjs.com/signup
-[Tutorial]: ../tutorial/index.html

docs/src/tutorials/hybrid-applications-with-webpack/index.md

@@ -6,7 +6,7 @@ and the `wasm-pack` workflow by building the example app in the template.
 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 read and followed the [Prerequisites](../prerequisites/index.html).
+Be sure to have read and followed the [Prerequisites](../../../prerequisites/index.html).
 
 [Rust]: https://www.rust-lang.org
 [Node.js]: https://nodejs.org

docs/src/tutorials/npm-browser-packages/getting-started/manual-setup.md

@@ -80,7 +80,7 @@ pub fn greet() {
 }
 ```
 
-And that's it! We'll talk about what this code does in the [Tutorial], which you are all
+And that's it! We'll talk about what this code does in the [Tutorials], which you are all
 setup for now. Happy `wasm-pack`ing!
 
-[Tutorial]: ../tutorial/index.html
+[Tutorials]: ../tutorials/index.html

docs/src/tutorials/npm-browser-packages/index.md

@@ -8,11 +8,8 @@ much Rust knowledge to complete this tutorial.
 
 Be sure to have done the following before starting:
 
-1. [Install `wasm-pack`](../../installer)
-1. Read and install the [Prerequisites](../prerequisites/index.html).
-
-    - You'll need [Rust], version 1.30 or higher. (Currently either `beta` or `nightly` channels). [Learn more](../prerequisites/rust.html).
-    - You'll need [Node.js] and [npm] installed. You'll also need an npm Account. [Learn more](../prerequisites/npm.html).
+1. [Install `wasm-pack`](https://rustwasm.github.io/wasm-pack/installer/)
+1. Read and install the [Prerequisites](../../../prerequisites/index.html).
 
 ⚠️ We strongly recommend that you install [Node.js] using a version manager. You can learn more [here](https://npmjs.com/get-npm).
 

docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md

@@ -67,7 +67,6 @@ However, that's not the case! In Rust, the `^` is implied. You can read more abo
 
 [`wee_alloc`]: https://crates.io/crates/wee_alloc
 [`console_error_panic_hook`]: https://crates.io/crates/console_error_panic_hook
-[`cfg-if`]: https://crates.io/crates/cfg-if
 
 As part of our effort to design a template that helps people discover useful crates
 for their particular use case, this template includes two dependencies that can be
@@ -83,7 +82,6 @@ them both as dependencies, but also allows them to be optionally included.
 default = ["console_error_panic_hook"]
 
 [dependencies]
-cfg-if = "0.1.2"
 wasm-bindgen = "0.2"
 
 # The `console_error_panic_hook` crate provides better debugging of panics by
@@ -100,12 +98,10 @@ console_error_panic_hook = { version = "0.1.1", optional = true }
 wee_alloc = { version = "0.4.2", optional = true }
 ```
 
-[`cfg-if`] allows us to check if certain features are enabled on a Rust crate. We'll
-use this crate later to optionally enable [`console_error_panic_hook` or
-`wee_alloc`.
-
-By default, only `console_error_panic_hook` is enabled. To disable either
-feature, we can remove its name from the `default` vector.
+In our code, we'll mark certain parts of code as running only if certain `[features]`
+are enabled, specifically, `console_error_panic_hook` and `wee_alloc`. By default,
+only `console_error_panic_hook` is enabled. To disable or enable either feature, by
+default, we can edit the `default` vector under `[features]`.
 
 To learn more about these features, we discuss them in-depth in the [`src/lib.rs`] and
 [`src/utils.rs`] sections.

docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md

@@ -13,6 +13,25 @@ It contains three key parts:
 
 We'll start with the most important part of `lib.rs` -- the two `#[wasm_bindgen]` functions (which you can find at the bottom of the file). In many cases, this is the only part of `lib.rs` you will need to modify.
 
+## 1. Using `wasm_bindgen`
+
+To expose functionality from the `wasm-bindgen` crate more conveniently we can use the `use` keyword.
+`use` allows us to conveniently refer to parts of a crate or module. You can learn more about how Rust
+lets you write modular code in [this chapter of the book](https://doc.rust-lang.org/book/ch07-02-modules-and-use-to-control-scope-and-privacy.html).
+
+```rust
+use wasm_bindgen::prelude::*;
+```
+
+Many crates contain a prelude, a list of things that are convenient to import
+all at once. This allows common features of the module to be conveniently
+accessed without a lengthy prefix. For example, in this file we can use
+`#[wasm_bindgen]` only because it is brought into scope by the prelude.
+
+The asterisk at the end of this `use` indicates that everything inside the module `wasm_bindgen::prelude` (i.e. the module `prelude` inside the crate `wasm_bindgen`) can be referred to without prefixing it with `wasm_bindgen::prelude`.
+
+For example, `#[wasm_bindgen]` could also be written as `#[wasm_bindgen::prelude::wasm_bindgen]`, although this is not recommended.
+
 ## 1. `#[wasm_bindgen]` functions
 
 The `#[wasm_bindgen]` attribute indicates that the function below it will be accessible both in JavaScript and Rust.
@@ -63,43 +82,19 @@ Either way, the contents of `utils.rs` define a single public function `set_pani
 
 
 ```rust
-use cfg_if::cfg_if;
+    // When the `wee_alloc` feature is enabled, use `wee_alloc` as the global
+    // When the `wee_alloc` feature is enabled, use `wee_alloc` as the global	// allocator.
+    // allocator.	#[cfg(feature = "wee_alloc")]
+    if #[cfg(feature = "wee_alloc")] {	#[global_allocator]
+        #[global_allocator]	static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
 ```
 
-`use` allows us to conveniently refer to parts of a crate or module. For example, suppose the crate `cfg_if` contains a function `func`. It is always possible to call this function directly by writing `cfg_if::func()`. However, this is often tedious to write. If we first specify `use cfg_if::func;`, then `func` can be called by just writing `func()` instead. You can learn more about how Rust let's you
-write modular code in [this chapter of the book](https://doc.rust-lang.org/book/ch07-02-modules-and-use-to-control-scope-and-privacy.html).
-
-With this in mind, this `use` allows us to call the macro `cfg_if!` inside the crate `cfg_if` without writing `cfg_if::cfg_if!`. We use `cfg_if!` to configure `wee_alloc`, which we will talk more about in a [separate section](./wee_alloc.md):
-
-```rust
-cfg_if! {
-    if #[cfg(feature = "wee_alloc")] {
-        #[global_allocator]
-        static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
-    }
-}
-```
-
-We immediately notice that `cfg_if!` is a macro because it ends in `!`, similarly to other Rust macros such as `println!` and `vec!`. A macro is directly replaced by other code during compile time.
-
 At compile time this will test if the `wee_alloc` feature is enabled for this
 compilation. If it's enabled we'll configure a global allocator (according to
 [`wee_alloc`'s docs][wee-alloc-docs]), otherwise it'll compile to nothing.
 
 [wee-alloc-docs]: https://docs.rs/wee_alloc/0.4.3/wee_alloc/
 
-As we saw earlier, the `default` vector in `[features]` only contains `"console_error_panic_hook"` and not `"wee_alloc"`. So, in this case, the `cfg_if!` block will be replaced by no code at all, and hence the default memory allocator will be used instead of `wee_alloc`.
-
-```rust
-use wasm_bindgen::prelude::*;
-```
-
-Many crates contain a prelude, a list of things that are convenient to import
-all at once. This allows common features of the module to be conveniently
-accessed without a lengthy prefix. For example, in this file we can use
-`#[wasm_bindgen]` only because it is brought into scope by the prelude.
-
-The asterisk at the end of this `use` indicates that everything inside the module `wasm_bindgen::prelude` (i.e. the module `prelude` inside the crate `wasm_bindgen`) can be referred to without prefixing it with `wasm_bindgen::prelude`.
-
-For example, `#[wasm_bindgen]` could also be written as `#[wasm_bindgen::prelude::wasm_bindgen]`, although this is not recommended.
+As we saw earlier, the `default` vector in `[features]` only contains `"console_error_panic_hook"` and not `"wee_alloc"`. So, in this case, this 
+block will be replaced by no code at all, and hence the default memory allocator will be used instead of `wee_alloc`.
 

docs/src/tutorials/npm-browser-packages/template-deep-dive/src-utils-rs.md

@@ -14,46 +14,22 @@ We will discuss:
 ## 1. Defining `set_panic_hook`
 
 ```rust
-use cfg_if::cfg_if;
-```
-
-This allows us to write `cfg_if!` instead of `cfg_if::cfg_if!`, identically to the line in `src/lib.rs`.
-
-```rust
-cfg_if! {
-    if #[cfg(feature = "console_error_panic_hook")] {
-        pub use self::console_error_panic_hook::set_once as set_panic_hook;
-    } else {
-        #[inline]
-        pub fn set_panic_hook() {}
-    }
+pub fn set_panic_hook() {
+    // When the `console_error_panic_hook` feature is enabled, we can call the
+    // `set_panic_hook` function at least once during initialization, and then
+    // we will get better error messages if our code ever panics.
+    //
+    // For more details see
+    // https://github.com/rustwasm/console_error_panic_hook#readme
+    #[cfg(feature = "console_error_panic_hook")]
+    console_error_panic_hook::set_once();
 }
 ```
 
-As described in the preceding section, this invocation of the `cfg_if!`
-tests whether the `console_error_panic_hook` feature is enabled at compile time,
-replacing with the statements in the `if` block or with those in the `else`
-block. These two cases are:
-
-```rust
-pub use self::console_error_panic_hook::set_once as set_panic_hook;
-```
-
-This `use` statement means the function
-`self::console_error_panic_hook::set_once` can now be accessed more conveniently
-as `set_panic_hook`. With `pub`, this function will be accessible
-outside of the `utils` module as `utils::set_panic_hook`.
-
-```rust
-#[inline]
-pub fn set_panic_hook() {}
-```
-
-Here, `set_panic_hook` is defined to be an empty inline function. The inline
-annotation here means that whenever the function is called the function call is
-replaced with the body of the function, which is for `set_panic_hook` nothing!
-This allows the use of `set_panic_hook` without any run-time or code-size
-performance penalty if the feature is not enabled.
+Here, we define a function that's preceded by a `cfg` attribute. This attribue,
+`#[cfg(feature = "console_error_panic_hook")]`, tells Rust to check if the 
+`console_error_panic_hook` feature is set at compile time. If it is, it will call
+this function. If it isn't- it won't! 
 
 ## 2. What is `console_error_panic_hook`?