Updated wasm_bindgen docs (#547)

* Updated docs

* Regenerate documentation

Co-authored-by: David Freese <freese@verily.com>

docs/flatten.md

@@ -943,6 +943,18 @@ rust_wasm_bindgen(<a href="#rust_wasm_bindgen-name">name</a>, <a href="#rust_was
 
 Generates javascript and typescript bindings for a webassembly module.
 
+To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the
+external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup):
+
+```python
+load("@io_bazel_rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositories")
+
+rust_wasm_bindgen_repositories()
+```
+
+An example of this rule in use can be seen at [@io_bazel_rules_rust//examples/wasm/...](../examples/wasm)
+
+
 **ATTRIBUTES**
 
 
@@ -963,6 +975,32 @@ rust_wasm_bindgen_toolchain(<a href="#rust_wasm_bindgen_toolchain-name">name</a>
 
 The tools required for the `rust_wasm_bindgen` rule.
 
+You can also use your own version of wasm-bindgen using the toolchain rules below:
+
+```python
+load("@io_bazel_rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
+
+rust_bindgen_toolchain(
+    bindgen = "//my/raze:cargo_bin_wasm_bindgen",
+)
+
+toolchain(
+    name = "wasm-bindgen-toolchain",
+    toolchain = "wasm-bindgen-toolchain-impl",
+    toolchain_type = "@io_bazel_rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
+)
+```
+
+Now that you have your own toolchain, you need to register it by
+inserting the following statement in your `WORKSPACE` file:
+
+```python
+register_toolchains("//my/toolchains:wasm-bindgen-toolchain")
+```
+
+For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+
+
 **ATTRIBUTES**
 
 

docs/rust_wasm_bindgen.md

@@ -12,6 +12,18 @@ rust_wasm_bindgen(<a href="#rust_wasm_bindgen-name">name</a>, <a href="#rust_was
 
 Generates javascript and typescript bindings for a webassembly module.
 
+To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the
+external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup):
+
+```python
+load("@io_bazel_rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositories")
+
+rust_wasm_bindgen_repositories()
+```
+
+An example of this rule in use can be seen at [@io_bazel_rules_rust//examples/wasm/...](../examples/wasm)
+
+
 **ATTRIBUTES**
 
 
@@ -32,6 +44,32 @@ rust_wasm_bindgen_toolchain(<a href="#rust_wasm_bindgen_toolchain-name">name</a>
 
 The tools required for the `rust_wasm_bindgen` rule.
 
+You can also use your own version of wasm-bindgen using the toolchain rules below:
+
+```python
+load("@io_bazel_rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
+
+rust_bindgen_toolchain(
+    bindgen = "//my/raze:cargo_bin_wasm_bindgen",
+)
+
+toolchain(
+    name = "wasm-bindgen-toolchain",
+    toolchain = "wasm-bindgen-toolchain-impl",
+    toolchain_type = "@io_bazel_rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
+)
+```
+
+Now that you have your own toolchain, you need to register it by
+inserting the following statement in your `WORKSPACE` file:
+
+```python
+register_toolchains("//my/toolchains:wasm-bindgen-toolchain")
+```
+
+For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+
+
 **ATTRIBUTES**
 
 

wasm_bindgen/README.md

@@ -1,65 +1,8 @@
 # Rust WebAssembly Bindgen Rules
 
-<div class="toc">
-  <h2>Rules</h2>
-  <ul>
-    <li><a href="docs/index.md#rust_wasm_bindgen_toolchain">rust_wasm_bindgen_toolchain</a></li>
-    <li>rust_wasm_bindgen_library</li>
-  </ul>
-</div>
-
-## Overview
-
 These rules are for using [Wasm Bindgen][wasm_bindgen] to generate [Rust][rust] bindings to.
 
 [rust]: http://www.rust-lang.org/
 [wasm_bindgen]: https://github.com/rustwasm/wasm-bindgen
 
-See the [wasm bindgen example](../examples/hello_world_wasm/BUILD#L25) for a more complete example of use.
-
-### Setup
-
-To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the
-external repositories for the Rust bindgen toolchain (in addition to the [rust rules setup](..)):
-
-```python
-load("@io_bazel_rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositories")
-
-rust_wasm_bindgen_repositories()
-```
-This makes the default toolchain defined in [`@io_bazel_rules_rust`](./BUILD) available.
-
-[raze]: https://github.com/google/cargo-raze
-
-It will load crate dependencies of bindgen that are generated using
-[cargo raze][raze] inside the rules_rust
-repository. However, using those dependencies might conflict with other uses
-of [cargo raze][raze]. If you need to change
-those dependencies, please see the [dedicated section below](#custom-deps).
-
-For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
-
-## <a name="custom-toolchains">Customizing toolchains
-
-You can also use your own version of wasm-bindgen using the toolchain rules below:
-
-```python
-load("@io_bazel_rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
-
-rust_bindgen_toolchain(
-    bindgen = "//my/raze:cargo_bin_wasm_bindgen",
-)
-
-toolchain(
-    name = "wasm-bindgen-toolchain",
-    toolchain = "wasm-bindgen-toolchain-impl",
-    toolchain_type = "@io_bazel_rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
-)
-```
-
-Now that you have your own toolchain, you need to register it by
-inserting the following statement in your `WORKSPACE` file:
-
-```python
-register_toolchains("//my/toolchains:wasm-bindgen-toolchain")
-```
+More information can be found in the [rules_rust documentation](https://bazelbuild.github.io/rules_rust/rust_wasm_bindgen.html).

wasm_bindgen/repositories.bzl

@@ -17,7 +17,12 @@ load("//wasm_bindgen/raze:crates.bzl", "rules_rust_wasm_bindgen_fetch_remote_cra
 
 # buildifier: disable=unnamed-macro
 def rust_wasm_bindgen_repositories():
-    """Declare dependencies needed for wasm-bindgen."""
+    """Declare dependencies needed for wasm-bindgen.
+    
+    This macro will load crate dependencies of `wasm-bindgen` that are generated using [cargo raze][raze] inside the rules_rust \
+    repository. This makes the default toolchain `@io_bazel_rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain` available. For \
+    more information on `wasm_bindgen` toolchains, see [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain).
+    """
 
     rules_rust_wasm_bindgen_fetch_remote_crates()
 

wasm_bindgen/wasm_bindgen.bzl

@@ -15,6 +15,50 @@
 # buildifier: disable=module-docstring
 load("@io_bazel_rules_rust//rust:private/transitions.bzl", "wasm_bindgen_transition")
 
+_WASM_BINDGEN_DOC = """\
+Generates javascript and typescript bindings for a webassembly module.
+
+To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the
+external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup):
+
+```python
+load("@io_bazel_rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositories")
+
+rust_wasm_bindgen_repositories()
+```
+
+An example of this rule in use can be seen at [@io_bazel_rules_rust//examples/wasm/...](../examples/wasm)
+"""
+
+_WASM_BINDGEN_TOOLCHAIN_DOC = """\
+The tools required for the `rust_wasm_bindgen` rule.
+
+You can also use your own version of wasm-bindgen using the toolchain rules below:
+
+```python
+load("@io_bazel_rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
+
+rust_bindgen_toolchain(
+    bindgen = "//my/raze:cargo_bin_wasm_bindgen",
+)
+
+toolchain(
+    name = "wasm-bindgen-toolchain",
+    toolchain = "wasm-bindgen-toolchain-impl",
+    toolchain_type = "@io_bazel_rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
+)
+```
+
+Now that you have your own toolchain, you need to register it by
+inserting the following statement in your `WORKSPACE` file:
+
+```python
+register_toolchains("//my/toolchains:wasm-bindgen-toolchain")
+```
+
+For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+"""
+
 def _rust_wasm_bindgen_impl(ctx):
     toolchain = ctx.toolchains["@io_bazel_rules_rust//wasm_bindgen:wasm_bindgen_toolchain"]
     bindgen_bin = toolchain.bindgen
@@ -86,7 +130,7 @@ def _rust_wasm_bindgen_impl(ctx):
 
 rust_wasm_bindgen = rule(
     implementation = _rust_wasm_bindgen_impl,
-    doc = "Generates javascript and typescript bindings for a webassembly module.",
+    doc = _WASM_BINDGEN_DOC,
     attrs = {
         "wasm_file": attr.label(
             doc = "The .wasm file to generate bindings for.",
@@ -119,7 +163,7 @@ def _rust_wasm_bindgen_toolchain_impl(ctx):
 
 rust_wasm_bindgen_toolchain = rule(
     implementation = _rust_wasm_bindgen_toolchain_impl,
-    doc = "The tools required for the `rust_wasm_bindgen` rule.",
+    doc = _WASM_BINDGEN_TOOLCHAIN_DOC,
     attrs = {
         "bindgen": attr.label(
             doc = "The label of a `wasm-bindgen` executable.",