Generate README.mds for each crate from its top-level docs

Uses `cargo readme` to generate `README.md`s from each crate's top-level
docs. This also preserves test-ability of doc examples.

.README.tpl

@@ -0,0 +1,23 @@
+<div align="center">
+
+  <h1><code>{{crate}}</code></h1>
+
+  <p>
+    <a href="https://travis-ci.org/rustasync/{{crate}}"><img src="https://img.shields.io/azure-devops/build/rustwasm/gloo/6.svg?style=flat-square" alt="Build Status" /></a>
+    <a href="https://crates.io/crates/{{crate}}"><img src="https://img.shields.io/crates/v/{{crate}}.svg?style=flat-square" alt="Crates.io version" /></a>
+    <a href="https://crates.io/crates/{{crate}}"><img src="https://img.shields.io/crates/d/{{crate}}.svg?style=flat-square" alt="Download" /></a>
+    <a href="https://docs.rs/{{crate}}"><img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /></a>
+  </p>
+
+  <h3>
+    <a href="https://docs.rs/{{crate}}">API Docs</a>
+    <span> | </span>
+    <a href="https://github.com/rustwasm/gloo/blob/master/CONTRIBUTING.md">Contributing</a>
+    <span> | </span>
+    <a href="https://discordapp.com/channels/442252698964721669/443151097398296587">Chat</a>
+  </h3>
+
+  <sub>Built with 🦀🕸 by <a href="https://rustwasm.github.io/">The Rust and WebAssembly Working Group</a></sub>
+</div>
+
+{{readme}}

.azure-pipelines.yml

@@ -13,6 +13,10 @@ jobs:
           export RUST_BACKTRACE=1
           cargo test --all || exit
         displayName: Run cargo check and test
+  - job: test_cargo_readme
+    displayName: "Test `README.md`s are up to date"
+    steps:
+      - template: .ci/test-cargo-readme.yml
   - job: test_headless_firefox
     displayName: "Headless Browser Tests (Firefox)"
     steps:

.ci/test-cargo-readme.yml

@@ -0,0 +1,20 @@
+steps:
+  - template: ./install-rust.yml
+    parameters:
+      rust_version: stable
+  - script: |
+      cargo install cargo-readme
+    displayName: "Install `cargo readme`"
+  - script: |
+      cargo readme --version
+    displayName: "Query `cargo readme` version"
+  - script: |
+      set -ex
+      ./update-readmes.sh
+      git diff --exit-code --name-only || {
+          echo 'Error: Found `README.md`s that are not up to date!'
+          echo
+          echo 'Run `./update-readmes.sh` and commit the changes.'
+          exit 1
+      }
+    displayName: "Test `README.md`s are up to date"

.gitattributes

@@ -0,0 +1,3 @@
+# These are programmatically generated with `cargo readme` so don't clutter
+# diffs with them and don't try and merge them.
+crates/*/README.md -diff -merge

CONTRIBUTING.md

@@ -19,6 +19,7 @@ yourself.
     - [Wasm Headless Browser Tests](#wasm-headless-browser-tests)
     - [Non-Wasm Tests](#non-wasm-tests)
   - [Formatting](#formatting)
+  - [Updating `README.md`s](#updating-readmemds)
 - [Workflow](#workflow)
   - [Proposing a Design](#proposing-a-design)
     - [Design Checklist](#design-checklist)
@@ -48,10 +49,13 @@ These tools are required for building and testing Gloo:
   the whole code base.
 * [**`wasm-pack`:**][install-wasm-pack] We use `wasm-pack` to orchestrate
   headless browser testing.
+* [**`cargo readme`:**][cargo-readme] We use `cargo readme` to generate
+  `README.md`s from each crate's module documentation.
 
 [install-rust]: https://www.rust-lang.org/tools/install
 [rustfmt]: https://github.com/rust-lang/rustfmt
 [install-wasm-pack]: https://rustwasm.github.io/wasm-pack/installer/
+[cargo-readme]: https://github.com/livioribeiro/cargo-readme
 
 ### Building
 
@@ -99,6 +103,15 @@ To (re)format the Gloo source code, run:
 $ cargo fmt --all
 ```
 
+### Updating `README.md`s
+
+To update each `gloo/crates/*/README.md` to reflect the crate's top-level
+documentation, go to the root of the repository and run:
+
+```
+./update-readmes.sh
+```
+
 ## Workflow
 
 Designing APIs for Gloo, its utility crates, and interfaces between them takes a

crates/console-timer/README.md

@@ -0,0 +1,67 @@
+<div align="center">
+
+  <h1><code>gloo-console-timer</code></h1>
+
+  <p>
+    <a href="https://travis-ci.org/rustasync/gloo-console-timer"><img src="https://img.shields.io/azure-devops/build/rustwasm/gloo/6.svg?style=flat-square" alt="Build Status" /></a>
+    <a href="https://crates.io/crates/gloo-console-timer"><img src="https://img.shields.io/crates/v/gloo-console-timer.svg?style=flat-square" alt="Crates.io version" /></a>
+    <a href="https://crates.io/crates/gloo-console-timer"><img src="https://img.shields.io/crates/d/gloo-console-timer.svg?style=flat-square" alt="Download" /></a>
+    <a href="https://docs.rs/gloo-console-timer"><img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /></a>
+  </p>
+
+  <h3>
+    <a href="https://docs.rs/gloo-console-timer">API Docs</a>
+    <span> | </span>
+    <a href="https://github.com/rustwasm/gloo/blob/master/CONTRIBUTING.md">Contributing</a>
+    <span> | </span>
+    <a href="https://discordapp.com/channels/442252698964721669/443151097398296587">Chat</a>
+  </h3>
+
+  <sub>Built with 🦀🕸 by <a href="https://rustwasm.github.io/">The Rust and WebAssembly Working Group</a></sub>
+</div>
+
+
+The `console.time` and `console.timeEnd` functions allow you to log the
+timing of named operations to the browser's developer tools console. You
+call `console.time("foo")` when the operation begins, and call
+`console.timeEnd("foo")` when it finishes.
+
+Additionally, these measurements will show up in your browser's profiler's
+"timeline" or "waterfall" view.
+
+[See MDN for more info](https://developer.mozilla.org/en-US/docs/Web/API/console#Timers).
+
+This API wraps both the `time` and `timeEnd` calls into a single type
+named `ConsoleTimer`, ensuring both are called.
+
+### Scoped Measurement
+
+Wrap code to be measured in a closure with `ConsoleTimer::scope`.
+
+```rust
+use gloo_console_timer::ConsoleTimer;
+
+let value = ConsoleTimer::scope("foo", || {
+    // Place code to be measured here
+    // Optionally return a value.
+});
+```
+
+### RAII-Style Measurement
+
+For scenarios where `ConsoleTimer::scope` can't be used, like with
+asynchronous operations, you can use `ConsoleTimer::new` to create a timer.
+The measurement ends when the timer object goes out of scope / is dropped.
+
+```rust
+use gloo_console_timer::ConsoleTimer;
+use gloo_timers::callback::Timeout;
+
+// Start timing a new operation.
+let timer = ConsoleTimer::new("foo");
+
+// And then asynchronously finish timing.
+let timeout = Timeout::new(1_000, move || {
+    drop(timer);
+});
+```

crates/events/README.md

@@ -0,0 +1,25 @@
+<div align="center">
+
+  <h1><code>gloo-events</code></h1>
+
+  <p>
+    <a href="https://travis-ci.org/rustasync/gloo-events"><img src="https://img.shields.io/azure-devops/build/rustwasm/gloo/6.svg?style=flat-square" alt="Build Status" /></a>
+    <a href="https://crates.io/crates/gloo-events"><img src="https://img.shields.io/crates/v/gloo-events.svg?style=flat-square" alt="Crates.io version" /></a>
+    <a href="https://crates.io/crates/gloo-events"><img src="https://img.shields.io/crates/d/gloo-events.svg?style=flat-square" alt="Download" /></a>
+    <a href="https://docs.rs/gloo-events"><img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /></a>
+  </p>
+
+  <h3>
+    <a href="https://docs.rs/gloo-events">API Docs</a>
+    <span> | </span>
+    <a href="https://github.com/rustwasm/gloo/blob/master/CONTRIBUTING.md">Contributing</a>
+    <span> | </span>
+    <a href="https://discordapp.com/channels/442252698964721669/443151097398296587">Chat</a>
+  </h3>
+
+  <sub>Built with 🦀🕸 by <a href="https://rustwasm.github.io/">The Rust and WebAssembly Working Group</a></sub>
+</div>
+
+Using event listeners with [`web-sys`](https://crates.io/crates/web-sys) is hard! This crate provides an [`EventListener`](struct.EventListener.html) type which makes it easy!
+
+See the documentation for [`EventListener`](struct.EventListener.html) for more information.

crates/timers/README.md

@@ -0,0 +1,52 @@
+<div align="center">
+
+  <h1><code>gloo-timers</code></h1>
+
+  <p>
+    <a href="https://travis-ci.org/rustasync/gloo-timers"><img src="https://img.shields.io/azure-devops/build/rustwasm/gloo/6.svg?style=flat-square" alt="Build Status" /></a>
+    <a href="https://crates.io/crates/gloo-timers"><img src="https://img.shields.io/crates/v/gloo-timers.svg?style=flat-square" alt="Crates.io version" /></a>
+    <a href="https://crates.io/crates/gloo-timers"><img src="https://img.shields.io/crates/d/gloo-timers.svg?style=flat-square" alt="Download" /></a>
+    <a href="https://docs.rs/gloo-timers"><img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /></a>
+  </p>
+
+  <h3>
+    <a href="https://docs.rs/gloo-timers">API Docs</a>
+    <span> | </span>
+    <a href="https://github.com/rustwasm/gloo/blob/master/CONTRIBUTING.md">Contributing</a>
+    <span> | </span>
+    <a href="https://discordapp.com/channels/442252698964721669/443151097398296587">Chat</a>
+  </h3>
+
+  <sub>Built with 🦀🕸 by <a href="https://rustwasm.github.io/">The Rust and WebAssembly Working Group</a></sub>
+</div>
+
+
+Working with timers on the Web: `setTimeout` and `setInterval`.
+
+These APIs come in two flavors:
+
+1. a callback style (that more directly mimics the JavaScript APIs), and
+2. a `Future`s and `Stream`s API.
+
+### Timeouts
+
+Timeouts fire once after a period of time (measured in milliseconds).
+
+#### Timeouts with a Callback Function
+
+```rust
+use gloo_timers::callback::Timeout;
+
+let timeout = Timeout::new(1_000, move || {
+    // Do something after the one second timeout is up!
+});
+
+// Since we don't plan on cancelling the timeout, call `forget`.
+timeout.forget();
+```
+
+#### Timeouts as `Future`s
+
+With the `futures` feature enabled, a `future` module containing futures-based
+timers is exposed.
+

update-readmes.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+set -eux
+cd $(dirname $0)
+
+for c in crates/*; do
+    cd "$c"
+    cargo readme --template ../../.README.tpl > README.md
+    cd -
+done