From b47d1b8f0f30e86d8cbdbdfb249e47a37b25c044 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Tue, 21 Jul 2020 14:28:49 -0700 Subject: [PATCH] Rework docs for stable and async support. --- README.md | 104 +++++++++++++++++--------------- core/lib/Cargo.toml | 2 +- site/guide/1-quickstart.md | 9 ++- site/guide/2-getting-started.md | 44 ++++++-------- 4 files changed, 78 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 53f4934b..111e8f78 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ [![Matrix: #rocket:mozilla.org](https://img.shields.io/badge/style-%23rocket:mozilla.org-blue.svg?style=flat&label=[m])](https://chat.mozilla.org/#/room/#rocket:mozilla.org) [![IRC: #rocket on chat.freenode.net](https://img.shields.io/badge/style-%23rocket-blue.svg?style=flat&label=freenode)](https://kiwiirc.com/client/chat.freenode.net/#rocket) -Rocket is a web framework for Rust (nightly) with a focus on ease-of-use, -expressibility, and speed. Here's an example of a complete Rocket application: +Rocket is an async web framework for Rust with a focus on usability, security, +extensibility, and speed. ```rust #[macro_use] extern crate rocket; @@ -54,27 +54,10 @@ the [Kiwi IRC client] or a client of your own. [Matrix via Riot]: https://chat.mozilla.org/#/room/#rocket:mozilla.org [Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket -## Building +## Examples -### Nightly - -Rocket requires a nightly version of Rust as it makes heavy use of syntax -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 --all-features` - -### Examples - -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 +An extensive number of examples are provided in the `examples/` directory. Each +example can be compiled and run with Cargo. For instance, the following sequence of commands builds and runs the `Hello, world!` example: ```sh @@ -84,37 +67,57 @@ cargo run You should see `Hello, world!` by visiting `http://localhost:8000`. -## Testing +## Building and Testing -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. The `test.sh` script accepts no flags or either the -`--release` flag to test in release mode or the `--contrib` flag to test all -`contrib` modules individually. This script gets run by CI. +### Core and Contrib -To test a crate individually, run `cargo test --all-features` in the -corresponding crate directory. +The `core` directory contains the three core libraries: `lib`, `codegen`, and +`http`. The `contrib` directory contains officially supported community +contributions and similarly consists of `lib` and `codegen`. -### Core +Public APIs are exposed via `lib` packages: `core/lib` is distributed as the +`rocket` crate while `contrib/lib` is distributed as the `rocket_contrib` crate. +The remaining crates are implementation details. -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. +### Library Testing -### Codegen +Rocket's complete test suite can be run with `./scripts/test.sh` from the root +of the source tree. The script builds and tests all libraries and examples. It +accepts the following flags: -Code generation tests can be found in `codegen/tests`. We use the [compiletest] -library, which was extracted from `rustc`, for testing. See the [compiler test -documentation] for information on how to write compiler tests. + * `--contrib`: tests each `contrib` feature individually + * `--core`: tests each `core` feature individually + * `--release`: runs the testing suite in `release` mode -[compiletest]: https://crates.io/crates/compiletest_rs -[compiler test documentation]: https://github.com/rust-lang/rust/blob/master/src/test/COMPILER_TESTS.md +Additionally, a `+${toolchain}` flag, where `${toolchain}` is a valid `rustup` +toolchain string, can be passed as the first parameter. The flag is forwarded to +`cargo` commands. + +To test crates individually, simply run `cargo test --all-features` in the +crate's directory. + +### Codegen Testing + +Code generation diagnostics are tested using [`trybuild`]; tests can be found in +the `codegen/tests/ui-fail` directory of both `core` and `contrib`. Each test is +symlinked into sibling `ui-fail-stable` and `ui-fail-nightly` directories which +contain the expected error output for stable and nightly compilers, +respectively. + +[`trybuild`]: https://docs.rs/trybuild/1 ## Documentation -You can build the Rocket API documentation locally by running -`./scripts/mk-docs.sh`. The resulting documentation is what gets uploaded to -[api.rocket.rs](https://api.rocket.rs/). +API documentation is built with `./scripts/mk-docs.sh`. The resulting assets are +uploaded to [api.rocket.rs](https://api.rocket.rs/). + +Documentation for a released version `${x}` can be found at +`https://api.rocket.rs/v${x}`. For instance, the documentation for `0.4` can be +found at https://api.rocket.rs/v0.4. Documentation for unreleased versions in +branch `${branch}` be found at `https://api.rocket.rs/${branch}`. For instance, +the documentation for the `master` branch can be found at +https://api.rocket.rs/master. Documentation for unreleased branches is updated +periodically. ## Contributing @@ -133,14 +136,17 @@ come in many forms. You could: 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. + * **Commented:** Complex and non-obvious functionality must be properly + commented. + * **Documented:** Public items _must_ have doc comments with examples, if + applicable. + * **Styled:** Your code's style should match the existing and surrounding code + style. * **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. + * **Tested:** You must write (and pass) convincing tests for any new + functionality. + * **Focused:** Your code should do what it's supposed to and nothing more. All pull requests are code reviewed and tested by the CI. Note that unless you explicitly state otherwise, any contribution intentionally submitted for diff --git a/core/lib/Cargo.toml b/core/lib/Cargo.toml index 8579e515..8e95c0a3 100644 --- a/core/lib/Cargo.toml +++ b/core/lib/Cargo.toml @@ -3,7 +3,7 @@ name = "rocket" version = "0.5.0-dev" authors = ["Sergio Benitez "] description = """ -Web framework for nightly with a focus on ease-of-use, expressibility, and speed. +Web framework with a focus on usability, security, extensibility, and speed. """ documentation = "https://api.rocket.rs/v0.5/rocket/" homepage = "https://rocket.rs" diff --git a/site/guide/1-quickstart.md b/site/guide/1-quickstart.md index fdc8ebad..6964defc 100644 --- a/site/guide/1-quickstart.md +++ b/site/guide/1-quickstart.md @@ -1,10 +1,9 @@ # Quickstart -Before you can start writing a Rocket application, you'll need a **nightly** -version of Rust installed. We recommend you use [rustup](https://rustup.rs/) to -install or configure such a version. If you don't have Rust installed and would -like extra guidance doing so, see the [getting started](../getting-started) -section. +Before you can start writing a Rocket application, you'll need to install the +Rust toolchain. We recommend using [rustup](https://rustup.rs/). If you don't +have Rust installed and would like extra guidance doing so, see the [getting +started](../getting-started) section. ## Running Examples diff --git a/site/guide/2-getting-started.md b/site/guide/2-getting-started.md index 28347bd7..a7835b9d 100644 --- a/site/guide/2-getting-started.md +++ b/site/guide/2-getting-started.md @@ -1,40 +1,33 @@ # Getting Started Let's create and run our first Rocket application. We'll ensure we have a -compatible version of Rust, create a new Cargo project that depends on Rocket, -and then run the application. +compatible Rust toolchain installed, create a new Cargo project that depends on +Rocket, and then run the application. ## Installing Rust -Rocket makes abundant use of Rust's syntax extensions and other advanced, -unstable features. Because of this, we'll need to use a nightly version of Rust. -If you already have a working installation of the latest Rust nightly, feel free -to skip to the next section. +Rocket makes use of the latest Rust features. Because of this, we'll need a +recent release of Rust to run Rocket applications. If you already have a working +installation of the latest Rust compiler, feel free to skip to the next section. -To install a nightly version of Rust, we recommend using `rustup`. Install +To install the latst version of Rust, we recommend using `rustup`. Install `rustup` by following the instructions on [its website](https://rustup.rs/). -Once `rustup` is installed, configure Rust nightly as your default toolchain by -running the command: +Once `rustup` is installed, ensure the latest toolchain is installled by running +the command: ```sh -rustup default nightly +rustup default stable ``` -If you prefer, once we setup a project directory in the following section, you -can use per-directory overrides to use the nightly version _only_ for your -Rocket project by running the following command in the directory: +! note: You may prefer to develop using the _nightly_ channel. -```sh -rustup override set nightly -``` + The nightly Rust toolchain enables certain improved developer experiences, + such as better compile-time diagnostics, when developing with Rocket. You may + choose to develop on the nightly channel to take advantage of these improved + experiences. Note that all Rocket features are available across all Rust + channels. -! warning: Rocket requires the _latest_ version of Rust nightly. - - If your Rocket application suddenly stops building, ensure you're using the - latest version of Rust nightly and Rocket by updating your toolchain and - dependencies with: - - `rustup update && cargo update` + To set the nightly toolchain as your default, run `rustup default nightly`. ## Hello, world! @@ -64,7 +57,7 @@ fn index() -> &'static str { "Hello, world!" } -#[rocket::launch] +#[launch] fn rocket() -> rocket::Rocket { rocket::ignite().mount("/", routes![index]) } @@ -96,5 +89,4 @@ Visit `http://localhost:8000` to see your first Rocket application in action! You can disable colors and emoji by setting the `ROCKET_CLI_COLORS` environment variable to `0` or `off` when running a Rocket binary: - - `ROCKET_CLI_COLORS=off cargo run` + `ROCKET_CLI_COLORS=off cargo run`.