Revamp README: add documentation, testing, and contributing sections.

README.md

@@ -26,70 +26,86 @@ route resulting in the string `Hello, 58 year old named John!` being sent to the
 browser. If an `<age>` string was passed in that can't be parsed as a `u8`, the
 route won't get called, resulting in a 404 error.
 
-## Overview
+## Documentation
 
-Rocket employs code generation to remove the need for boilerplate involved with
-parsing requests and request parameters, prevent invalid and/or incorrect
-requests from invoking a user's request handler, and  allow the user to define
-what is valid and/or correct.
+Rocket is extensively documented:
 
-Rocket uses type _guards_, or _constraints_, on request handlers to
-accomplishing it's safety and correctness goals. In Rocket, handlers are _only_
-invoked if all types that appear in the request handler's argument list can be
-derived from the incoming request.
-
-In their simplest incarnation, guards can be types expected of parameters in a
-matched path. This is illustrated in the previous example where the `hello`
-request handler is only be invoked if the dynamic path parameter `<age>` parses
-as a `u8`. Guards can also be derived directly from a request. For instance, you
-can define an `AdminUser` type that can be derived only if the proper cookies
-were sent along with the request. Then, by simply including the type in a
-handler's argument list as follows:
-
-    #[get("/admin/post/<id>")]
-    fn admin(user: AdminUser, id: isize) ->  { .. }
-
-you can be assured that the handler will be invoked _only_ if an administrative
-user is logged in. Any number of such guards can be included. For example, to
-retrieve the request's cookies along with the admin user, simply include the
-`&Cookies` type in the argument list:
-
-    #[get("/admin/post/<id>")]
-    fn admin(user: AdminUser, cookies: &Cookies, id: isize) ->  { .. }
-
-Full documentation about built-in request guards is coming soon.
+  * [Quickstart](guide/quickstart): How to get started as quickly as possible.
+  * [Getting Started](guide/getting_started): How to start your first project.
+  * [Overview](overview): A brief introduction.
+  * [Guide](guide): A detailed guide and reference to every component.
+  * [API Documentation](api): The "rustdocs" (API documentation).
 
 ## Building
 
 ### Nightly
 
 Rocket requires a nightly version of Rust as it makes heavy use of syntax
-extensions. This also means that the first two unwieldly lines in the Rust file
-above are required.
+extensions. This means that the first two unwieldly lines in the introductory
+example above are required.
+
+### Core, Codegen, and Contrib
+
+All of the Rocket libraries are managed by Cargo. As a result, compiling them is
+simple.
+
+  * Core: `cd lib && cargo build`
+  * Codegen: `cd codegen && cargo build`
+  * Contrib: `cd contrib && cargo build`
 
 ### Examples
 
-Try running the examples in the `examples/` folder. For instance, the following
-sequence of commands builds and runs the `Hello, world!` example:
+Rocket ships with an extensive number of examples in the `examples/` directory
+which can be compiled and run with Cargo. For instance, the following sequence
+of commands builds and runs the `Hello, world!` example:
 
 ```
 cd examples/hello_world
 cargo run
 ```
 
-Then visit `localhost:8000`. You should see `Hello, world!`.
+You should see `Hello, world!` by visiting `http://localhost:8000`.
 
-### OS X
+## Testing
 
-Apple has stopped shipping `openssl` with OS X.11. As such, if your build fails
-to compile with some `openssl` related errors, you'll need to install `openssl`,
-`cargo clean`, and then `cargo build` again. Here are some lightweight
-instructions:
+To test Rocket, simply run `./scripts/test.sh` from the root of the source tree.
+This will build and test the `core`, `codegen`, and `contrib` libraries as well
+as all of the examples. This is the script that gets run by Travis CI.
 
-```
-brew install openssl
-brew link --force openssl
-export OPENSSL_INCLUDE_DIR=`brew --prefix openssl`/include
-export OPENSSL_LIB_DIR=`brew --prefix openssl`/lib
-```
+### Core
 
+Testing for the core library is done inline in the corresponding module. For
+example, the tests for routing can be found at the bottom of the
+`lib/src/router/mod.rs` file.
+
+### Codegen
+
+Code generation tests can be found in `codegen/tests`. We use the
+[compiletest](https://crates.io/crates/compiletest_rs) library, which was
+extracted from `rustc`, for testing. See the [compiler test
+documentation](https://github.com/rust-lang/rust/blob/master/COMPILER_TESTS.md)
+for information on how to write compiler tests.
+
+## Contributing
+
+Contributions are absolutely, positively welcome and encouraged! Contributions
+come in many forms. You could:
+
+  1. Submit a feature request or bug report as an [issue](https://github.com/SergioBenitez/Rocket/issues).
+  2. Comment on [issues that require
+        feedback](https://github.com/SergioBenitez/Rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22feedback+wanted%22).
+  3. Contribute code via [pull requests](https://github.com/SergioBenitez/Rocket/pulls).
+
+We aim to keep Rocket's code quality at the highest level. This means that any
+code you contribute must be:
+
+  * **Commented:** Public items _must_ be commented.
+  * **Documented:** Exposed items _must_ have rustdoc comments with
+    examples, if applicable.
+  * **Styled:** Your code should be `rustfmt`'d when possible.
+  * **Simple:** Your code should accomplish its task as simply and
+     idiomatically as possible.
+  * **Tested:** You must add (and pass) convincing tests for any functionality you add.
+  * **Focused:** Your code should do what it's supposed to do and nothing more.
+
+All pull requests are code reviewed and tested by the CI.