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

This commit is contained in:
Sergio Benitez 2016-09-29 18:56:11 -07:00
parent 85c06fde04
commit 4c96f6c71f
1 changed files with 62 additions and 46 deletions

108
README.md
View File

@ -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 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. route won't get called, resulting in a 404 error.
## Overview ## Documentation
Rocket employs code generation to remove the need for boilerplate involved with Rocket is extensively documented:
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 uses type _guards_, or _constraints_, on request handlers to * [Quickstart](guide/quickstart): How to get started as quickly as possible.
accomplishing it's safety and correctness goals. In Rocket, handlers are _only_ * [Getting Started](guide/getting_started): How to start your first project.
invoked if all types that appear in the request handler's argument list can be * [Overview](overview): A brief introduction.
derived from the incoming request. * [Guide](guide): A detailed guide and reference to every component.
* [API Documentation](api): The "rustdocs" (API documentation).
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.
## Building ## Building
### Nightly ### Nightly
Rocket requires a nightly version of Rust as it makes heavy use of syntax 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 extensions. This means that the first two unwieldly lines in the introductory
above are required. 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 ### Examples
Try running the examples in the `examples/` folder. For instance, the following Rocket ships with an extensive number of examples in the `examples/` directory
sequence of commands builds and runs the `Hello, world!` example: 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 cd examples/hello_world
cargo run 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 test Rocket, simply run `./scripts/test.sh` from the root of the source tree.
to compile with some `openssl` related errors, you'll need to install `openssl`, This will build and test the `core`, `codegen`, and `contrib` libraries as well
`cargo clean`, and then `cargo build` again. Here are some lightweight as all of the examples. This is the script that gets run by Travis CI.
instructions:
``` ### Core
brew install openssl
brew link --force openssl
export OPENSSL_INCLUDE_DIR=`brew --prefix openssl`/include
export OPENSSL_LIB_DIR=`brew --prefix openssl`/lib
```
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.