Add the `bindgen` Users Guide

This commit adds a Users Guide, built with [mdbook][] (the same tool used
by *The Rust Book*).

It moves all the user documentation from the README.md into the Users Guide. It
leaves the README.md as a splash page featuring an example of what `bindgen` is
and does, a link to the Users Guide, a link to the docs.rs/bindgen API reference
documentation, and a link to CONTRIBUTING.md.

It ensures that the Users Guide builds with `mdbook`, and all code snippets
within it build as doctests and pass, on every CI run.

Finally, it builds and uploads the Users Guide every time CI passes on the
master branch.

[mdbook]: https://github.com/azerupi/mdBook

1 files changed, 26 insertions, 208 deletions

diff --git a/README.md b/README.md
index 9c219ef5..055ac7a7 100644
--- a/README.md
+++ b/README.md
@@ -1,227 +1,45 @@
 # `bindgen`
 
-Automatically generates Rust FFI bindings to C and C++ libraries.
+**`bindgen` automatically generates Rust FFI bindings to C and C++ libraries.**
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+For example, given the C header `cool.h`:
 
+```c
+typedef struct CoolStruct {
+    int x;
+    int y;
+} CoolStruct;
 
-- [Usage](#usage)
-  - [Requirements](#requirements)
-    - [Installing Clang 3.9](#installing-clang-39)
-      - [Windows](#windows)
-      - [OSX](#osx)
-      - [Debian-based Linuxes](#debian-based-linuxes)
-      - [Arch](#arch)
-      - [From source](#from-source)
-  - [Library usage with `build.rs`](#library-usage-with-buildrs)
-    - [`build.rs` Tutorial](#buildrs-tutorial)
-    - [Simple Example: `./bindgen-integration`](#simple-example-bindgen-integration)
-    - [Real World Example: Stylo](#real-world-example-stylo)
-  - [Command Line Usage](#command-line-usage)
-  - [C++](#c)
-  - [Annotations](#annotations)
-    - [`opaque`](#opaque)
-    - [`hide`](#hide)
-    - [`replaces`](#replaces)
-    - [`nocopy`](#nocopy)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
-## Usage
-
-### Requirements
-
-It is recommended to use Clang 3.9 or greater, however `bindgen` can run with
-older Clangs with some features disabled.
-
-#### Installing Clang 3.9
-
-##### Windows
-
-Download and install the official pre-built binary from
-[LLVM download page](http://releases.llvm.org/download.html).
-
-##### OSX
-
-If you use Homebrew:
-
-```
-$ brew install llvm
-```
-
-If you use MacPorts:
-
-```
-$ port install clang-3.9
-```
-
-##### Debian-based Linuxes
-
+void cool_function(int i, char c, CoolStruct* cs);
 ```
-# apt-get install llvm-3.9-dev libclang-3.9-dev clang-3.9
-```
-
-Ubuntu 16.10 provides the necessary packages directly. If you are using older
-version of Ubuntu or other Debian-based distros, you may need to add the LLVM
-repos to get version 3.9. See http://apt.llvm.org/.
-
-##### Arch
-
-```
-# pacman -S clang
-```
-
-##### From source
-
-If your package manager doesn't yet offer Clang 3.9, you'll need to build from
-source. For that, follow the instructions
-[here](http://clang.llvm.org/get_started.html).
-
-Those instructions list optional steps. For bindgen:
-
-* Checkout and build clang
-* Checkout and build the extra-clang-tools
-* Checkout and build the compiler-rt
-* You do not need to checkout or build libcxx
-
-### Library usage with `build.rs`
-
-💡 This is the recommended way to use `bindgen`. 💡
-
-#### `build.rs` Tutorial
-
-[Here is a step-by-step tutorial for generating FFI bindings to the `bzip2` C library.][tutorial]
-
-[tutorial]: http://fitzgeraldnick.com/2016/12/14/using-libbindgen-in-build-rs.html
-
-#### Simple Example: `./bindgen-integration`
-
-The [`./bindgen-integration`][integration] directory has an example crate that
-generates FFI bindings in `build.rs` and can be used a template for new
-projects.
-
-[integration]: ./bindgen-integration
 
-#### Real World Example: Stylo
-
-A real world example is [the Stylo build script][stylo-script] used for
-integrating Servo's layout system into Gecko.
-
-[stylo-script]: https://github.com/servo/servo/blob/master/components/style/build_gecko.rs
-
-In `Cargo.toml`:
-
-```toml
-[package]
-# ...
-build = "build.rs"
-
-[build-dependencies]
-bindgen = "0.20"
-```
-
-In `build.rs`:
+`bindgen` produces Rust FFI code allowing you to call into the `cool` library's
+functions and use its types:
 
 ```rust
-extern crate bindgen;
+/* automatically generated by rust-bindgen */
 
-use std::env;
-use std::path::Path;
-
-fn main() {
-  let out_dir = env::var("OUT_DIR").unwrap();
-  let _ = bindgen::builder()
-    .header("example.h")
-    .use_core()
-    .generate().unwrap()
-    .write_to_file(Path::new(&out_dir).join("example.rs"));
+#[repr(C)]
+pub struct CoolStruct {
+    pub x: ::std::os::raw::c_int,
+    pub y: ::std::os::raw::c_int,
 }
-```
-
-In `src/main.rs`:
-
-```rust
-include!(concat!(env!("OUT_DIR"), "/example.rs"));
-```
-
-### Command Line Usage
-
-```
-$ cargo install bindgen
-```
-
-There are a few options documented when running `bindgen --help`. Bindgen is installed to `~/.cargo/bin`. You have to add that directory to your path to use `bindgen`.
 
-### C++
-
-`bindgen` can handle most C++ features, but not all of them (C++ is hard!)
-
-Notable C++ features that are unsupported or only partially supported:
-
-* Partial template specialization
-* Traits templates
-* SFINAE
-* Instantiating new template specializations
-
-When passing in header files, the file will automatically be treated as C++ if
-it ends in ``.hpp``. If it doesn't, ``-x c++`` can be used to force C++ mode.
-
-You must use whitelisting when working with C++ to avoid pulling in all of the
-`std::*` types, some of which `bindgen` cannot handle. Additionally, you may
-want to blacklist other types that `bindgen` stumbles on, or make `bindgen`
-treat certain types as opaque.
-
-### Annotations
-
-The translation of classes, structs, enums, and typedefs can be adjusted using
-annotations. Annotations are specifically formatted html tags inside doxygen
-style comments.
-
-#### `opaque`
-
-The `opaque` annotation instructs bindgen to ignore all fields defined in
-a struct/class.
-
-```cpp
-/// <div rustbindgen opaque></div>
-```
-
-#### `hide`
-
-The `hide` annotation instructs bindgen to ignore the struct/class/field/enum
-completely.
-
-```cpp
-/// <div rustbindgen hide></div>
+extern "C" {
+    pub fn cool_function(i: ::std::os::raw::c_int,
+                         c: ::std::os::raw::c_char,
+                         cs: *mut CoolStruct);
+}
 ```
 
-#### `replaces`
+## Users Guide
 
-The `replaces` annotation can be used to use a type as a replacement for other
-(presumably more complex) type. This is used in Stylo to generate bindings for
-structures that for multiple reasons are too complex for bindgen to understand.
+[📚 Read the `bindgen` users guide here! 📚](https://servo.github.io/rust-bindgen)
 
-For example, in a C++ header:
-
-```cpp
-/**
- * <div rustbindgen replaces="nsTArray"></div>
- */
-template<typename T>
-class nsTArray_Simple {
-  T* mBuffer;
-public:
-  // The existence of a destructor here prevents bindgen from deriving the Clone
-  // trait via a simple memory copy.
-  ~nsTArray_Simple() {};
-};
-```
+## API Reference
 
-That way, after code generation, the bindings for the `nsTArray` type are
-the ones that would be generated for `nsTArray_Simple`.
+[API reference documentation is on docs.rs](https://docs.rs/bindgen)
 
-#### `nocopy`
+## Contributing
 
-The `nocopy` annotation is used to prevent bindgen to autoderive the `Copy`
-and `Clone` traits for a type.
+[See `CONTRIBUTING.md` for hacking on `bindgen`!](./CONTRIBUTING.md)