From 26ee13278264a181319005c9db8d9e79a84ccfe9 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Mon, 15 Oct 2018 22:50:35 -0700 Subject: [PATCH] Update site content for restructure. --- site/README.md | 35 +++++++--- .../{introduction.md => 0-introduction.md} | 0 site/guide/{quickstart.md => 1-quickstart.md} | 2 +- site/guide/{pastebin.md => 10-pastebin.md} | 17 +++-- .../guide/{conclusion.md => 11-conclusion.md} | 6 +- ...etting-started.md => 2-getting-started.md} | 0 site/guide/{overview.md => 3-overview.md} | 6 +- site/guide/{requests.md => 4-requests.md} | 70 +++++++++---------- site/guide/{responses.md => 5-responses.md} | 58 ++++++++------- site/guide/{state.md => 6-state.md} | 22 +++--- site/guide/{fairings.md => 7-fairings.md} | 40 +++++------ site/guide/{testing.md => 8-testing.md} | 25 ++++--- .../{configuration.md => 9-configuration.md} | 10 +-- site/{guide.md => guide/index.md} | 2 +- site/index.toml | 20 +++--- site/news/2017-02-06-version-0.2.md | 24 +++---- site/news/2017-07-14-version-0.3.md | 70 +++++++++---------- site/{news.toml => news/index.toml} | 0 site/overview.toml | 24 +++---- 19 files changed, 218 insertions(+), 213 deletions(-) rename site/guide/{introduction.md => 0-introduction.md} (100%) rename site/guide/{quickstart.md => 1-quickstart.md} (90%) rename site/guide/{pastebin.md => 10-pastebin.md} (95%) rename site/guide/{conclusion.md => 11-conclusion.md} (83%) rename site/guide/{getting-started.md => 2-getting-started.md} (100%) rename site/guide/{overview.md => 3-overview.md} (96%) rename site/guide/{requests.md => 4-requests.md} (91%) rename site/guide/{responses.md => 5-responses.md} (81%) rename site/guide/{state.md => 6-state.md} (91%) rename site/guide/{fairings.md => 7-fairings.md} (84%) rename site/guide/{testing.md => 8-testing.md} (85%) rename site/guide/{configuration.md => 9-configuration.md} (96%) rename site/{guide.md => guide/index.md} (98%) rename site/{news.toml => news/index.toml} (100%) diff --git a/site/README.md b/site/README.md index b9e99edc..9ddac220 100644 --- a/site/README.md +++ b/site/README.md @@ -7,20 +7,39 @@ website](https://rocket.rs). This directory contains the following: - * `index.toml` - Source data for the index (`/`). - * `news.toml` - Source data for the news page (`/news`). - * `overview.toml` - Source data for the overview page (`/overview`). - * `guide.md` - Index page for the [Rocket Programming Guide] (`/guide`). - * `news/*.md` - News articles linked to from `news.toml`. + * `index.toml` - Source data for the index. + * `overview.toml` - Source data for the overview page (`overview/`). + * `news/index.toml` - Source data for the news page (`news/`). + * `news/*.md` - News articles linked to from `news/index.toml`. * `guide/*.md` - Guide pages linked to from `guide.md`. [Rocket Programming Guide]: https://rocket.rs/guide/ ### Guide Links -Cross-linking to pages in the guide is accomplished via absolute links rooted at -`/guide/`. To link to the page whose source is at `guide/page.md`, for instance, -link to `/guide/page`. +Cross-linking guide pages is accomplished via relative links. Outside of the +index, this is: `../{page}#anchor`. For instance, to link to the **Quickstart > +Running Examples** page, use `../quickstart#running-examples`. + +### Aliases + +Aliases are shorthand URLs that start with `@` (e.g, `@api`). They are used +throughout the guide to simplify versioning URLs to Rocket's source code and the +Rocket API. They are replaced at build time with a URL prefix. At present, the +following aliases are available, where `${version}` is Rocket's version string +at the time of compilation: + + * `@example`: https://github.com/SergioBenitez/Rocket/tree/${version}/examples + * `@github`: https://github.com/SergioBenitez/Rocket/tree/${version} + * `@api`: https://api.rocket.rs/${version} + +For example, to link to `Rocket::launch()`, you might write: + +```md +Launch an instance of your application using the [`launch()`] method. + +[`launch()`]: @api/rocket/struct.Rocket.html#method.launch +``` ## License diff --git a/site/guide/introduction.md b/site/guide/0-introduction.md similarity index 100% rename from site/guide/introduction.md rename to site/guide/0-introduction.md diff --git a/site/guide/quickstart.md b/site/guide/1-quickstart.md similarity index 90% rename from site/guide/quickstart.md rename to site/guide/1-quickstart.md index a9865695..6b65a7d0 100644 --- a/site/guide/quickstart.md +++ b/site/guide/1-quickstart.md @@ -3,7 +3,7 @@ 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](/guide/getting-started) +like extra guidance doing so, see the [getting started](../getting-started) section. ## Running Examples diff --git a/site/guide/pastebin.md b/site/guide/10-pastebin.md similarity index 95% rename from site/guide/pastebin.md rename to site/guide/10-pastebin.md index cd819af2..54080562 100644 --- a/site/guide/pastebin.md +++ b/site/guide/10-pastebin.md @@ -100,7 +100,7 @@ string with the specified contents. Rocket will take the string and return it as the body of a fully formed HTTP response with `Content-Type: text/plain`. You can read more about how Rocket formulates responses at the [API documentation for the Responder - trait](https://api.rocket.rs/rocket/response/trait.Responder.html). + trait](@api/rocket/response/trait.Responder.html). Remember that routes first need to be mounted before Rocket dispatches requests to them. To mount the `index` route, modify the main function so that it reads: @@ -213,7 +213,7 @@ use rocket::Data; use rocket::http::RawStr; ``` -The [Data](https://api.rocket.rs/rocket/data/struct.Data.html) structure is key +The [Data](@api/rocket/data/struct.Data.html) structure is key here: it represents an unopened stream to the incoming request body data. We'll use it to efficiently stream the incoming request to a file. @@ -289,7 +289,7 @@ Here's a first take at implementing the `retrieve` route. The route below takes in an `` as a dynamic path element. The handler uses the `id` to construct a path to the paste inside `upload/`, and then attempts to open the file at that path, optionally returning the `File` if it exists. Rocket treats a `None` -[Responder](https://api.rocket.rs/rocket/response/trait.Responder.html#provided-implementations) +[Responder](@api/rocket/response/trait.Responder.html#provided-implementations) as a **404** error, which is exactly what we want to return when the requested paste doesn't exist. @@ -305,8 +305,7 @@ fn retrieve(id: &RawStr) -> Option { ``` Unfortunately, there's a problem with this code. Can you spot the issue? The -[`RawStr`](https://api.rocket.rs/rocket/http/struct.RawStr.html) type should tip -you off! +[`RawStr`](@api/rocket/http/struct.RawStr.html) type should tip you off! The issue is that the _user_ controls the value of `id`, and as a result, can coerce the service into opening files inside `upload/` that aren't meant to be @@ -320,7 +319,7 @@ provides the tools to prevent this and other kinds of attacks from happening. To prevent the attack, we need to _validate_ `id` before we use it. Since the `id` is a dynamic parameter, we can use Rocket's -[FromParam](https://api.rocket.rs/rocket/request/trait.FromParam.html) trait to +[FromParam](@api/rocket/request/trait.FromParam.html) trait to implement the validation and ensure that the `id` is a valid `PasteID` before using it. We do this by implementing `FromParam` for `PasteID` in `src/paste_id.rs`, as below: @@ -398,10 +397,10 @@ through some of them to get a better feel for Rocket. Here are some ideas: * Add a new route, `GET //` that syntax highlights the paste with ID `` for language ``. If `` is not a known language, do no highlighting. Possibly validate `` with `FromParam`. - * Use the [`local` module](https://api.rocket.rs/rocket/local/) to write - unit tests for your pastebin. + * Use the [`local` module](@api/rocket/local/) to write unit tests for your + pastebin. * Dispatch a thread before `launch`ing Rocket in `main` that periodically cleans up idling old pastes in `upload/`. You can find the full source code for the [completed pastebin tutorial on -GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/pastebin). +GitHub](@example/pastebin). diff --git a/site/guide/conclusion.md b/site/guide/11-conclusion.md similarity index 83% rename from site/guide/conclusion.md rename to site/guide/11-conclusion.md index a006d855..7e5fa7a2 100644 --- a/site/guide/conclusion.md +++ b/site/guide/11-conclusion.md @@ -22,7 +22,5 @@ guide. The best way to learn Rocket is to _build something_. It should be fun and easy, and there's always someone to help. Alternatively, you can read through the -[Rocket examples](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples) -or the [Rocket source -code](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/lib/src). Whatever you -decide to do next, we hope you have a blast! +[Rocket examples](@example) or the [Rocket source code](@github/lib/src). +Whatever you decide to do next, we hope you have a blast! diff --git a/site/guide/getting-started.md b/site/guide/2-getting-started.md similarity index 100% rename from site/guide/getting-started.md rename to site/guide/2-getting-started.md diff --git a/site/guide/overview.md b/site/guide/3-overview.md similarity index 96% rename from site/guide/overview.md rename to site/guide/3-overview.md index ff32d4bd..4b2f0e8a 100644 --- a/site/guide/overview.md +++ b/site/guide/3-overview.md @@ -71,7 +71,7 @@ fn world() -> &'static str { // <- request handler This declares the `world` route to match against the static path `"/world"` on incoming `GET` requests. The `world` route is simple, but additional route parameters are necessary when building more interesting applications. The -[Requests](/guide/requests) section describes the available options for +[Requests](../requests) section describes the available options for constructing routes. ## Mounting @@ -179,7 +179,7 @@ we expected. A version of this example's complete crate, ready to `cargo run`, can be found on -[GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/hello_world). +[GitHub](@example/hello_world). You can find dozens of other complete examples, spanning all of Rocket's features, in the [GitHub examples -directory](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/). +directory](@example/). diff --git a/site/guide/requests.md b/site/guide/4-requests.md similarity index 91% rename from site/guide/requests.md rename to site/guide/4-requests.md index 2e62f31d..cf78cbd3 100644 --- a/site/guide/requests.md +++ b/site/guide/4-requests.md @@ -38,7 +38,7 @@ to the root path: ``` The grammar for these attributes is defined formally in the -[`rocket_codegen`](https://api.rocket.rs/rocket_codegen/) API docs. +[`rocket_codegen`](@api/rocket_codegen/) API docs. ### HEAD Requests @@ -56,8 +56,8 @@ request methods under certain conditions. If a `POST` request contains a body of field has the name `_method` and a valid HTTP method name as its value (such as `"PUT"`), that field's value is used as the method for the incoming request. This allows Rocket applications to submit non-`POST` forms. The [todo -example](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/todo/static/index.html.tera#L47) -makes use of this feature to submit `PUT` and `DELETE` requests from a web form. +example](@example/todo/static/index.html.tera#L47) makes use of this feature to +submit `PUT` and `DELETE` requests from a web form. ## Dynamic Segments @@ -95,8 +95,8 @@ fn hello(name: String, age: u8, cool: bool) -> String { } ``` -[`FromParam`]: https://api.rocket.rs/rocket/request/trait.FromParam.html -[`FromParam` API docs]: https://api.rocket.rs/rocket/request/trait.FromParam.html +[`FromParam`]: @api/rocket/request/trait.FromParam.html +[`FromParam` API docs]: @api/rocket/request/trait.FromParam.html ### Raw Strings @@ -114,7 +114,7 @@ segment, a `RawStr` points to a potentially undecoded string. By contrast, a you want direct but potentially unsafe access to the string (`&RawStr`), or safe access to the string at the cost of an allocation (`String`). -[`RawStr`]: https://api.rocket.rs/rocket/http/struct.RawStr.html +[`RawStr`]: @api/rocket/http/struct.RawStr.html ## Forwarding @@ -215,7 +215,7 @@ fn files(file: PathBuf) -> Option { } ``` -[`FromSegments`]: https://api.rocket.rs/rocket/request/trait.FromSegments.html +[`FromSegments`]: @api/rocket/request/trait.FromSegments.html ## Format @@ -263,7 +263,7 @@ header will match `user`. If instead the route had been declared as `post`, Rocket would match the `format` against the `Content-Type` header of the incoming response. -[`ContentType::parse_flexible()`]: https://api.rocket.rs/rocket/http/struct.ContentType.html#method.parse_flexible +[`ContentType::parse_flexible()`]: @api/rocket/http/struct.ContentType.html#method.parse_flexible ## Request Guards @@ -295,8 +295,8 @@ short-circuiting; if one guard fails, the remaining are not attempted. To learn more about request guards and implementing them, see the [`FromRequest`] documentation. -[`FromRequest`]: https://api.rocket.rs/rocket/request/trait.FromRequest.html -[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html +[`FromRequest`]: @api/rocket/request/trait.FromRequest.html +[`Cookies`]: @api/rocket/http/enum.Cookies.html ### Custom Guards @@ -388,7 +388,7 @@ be set and removed using the `Cookies` guard. The [cookies example] on GitHub illustrates further use of the `Cookies` type to get and set cookies, while the [`Cookies`] documentation contains complete usage information. -[cookies example]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/cookies +[cookies example]: @example/cookies ### Private Cookies @@ -422,7 +422,7 @@ fn logout(mut cookies: Cookies) -> Flash { } ``` -[`Cookies::add()`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add +[`Cookies::add()`]: @api/rocket/http/enum.Cookies.html#method.add ### Secret Key @@ -439,12 +439,12 @@ Generating a string suitable for use as a `secret_key` configuration value is usually done through tools like `openssl`. Using `openssl`, a 256-bit base64 key can be generated with the command `openssl rand -base64 32`. -For more information on configuration, see the -[Configuration](/guide/configuration) section of the guide. +For more information on configuration, see the [Configuration](../configuration) +section of the guide. -[`get_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.get_private -[`add_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add_private -[`remove_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.remove_private +[`get_private`]: @api/rocket/http/enum.Cookies.html#method.get_private +[`add_private`]: @api/rocket/http/enum.Cookies.html#method.add_private +[`remove_private`]: @api/rocket/http/enum.Cookies.html#method.remove_private ### One-At-A-Time @@ -497,7 +497,7 @@ fn new(input: T) -> String { ... } Any type that implements [`FromData`] is also known as _data guard_. -[`FromData`]: https://api.rocket.rs/rocket/data/trait.FromData.html +[`FromData`]: @api/rocket/data/trait.FromData.html ### Forms @@ -533,8 +533,8 @@ forward or failure can be caught by using the `Option` and `Result` types: fn new(task: Option>) -> String { ... } ``` -[`FromForm`]: https://api.rocket.rs/rocket/request/trait.FromForm.html -[`FromFormValue`]: https://api.rocket.rs/rocket/request/trait.FromFormValue.html +[`FromForm`]: @api/rocket/request/trait.FromForm.html +[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html #### Lenient Parsing @@ -564,7 +564,7 @@ struct Task { .. } fn new(task: LenientForm) { .. } ``` -[`LenientForm`]: https://api.rocket.rs/rocket/request/struct.LenientForm.html +[`LenientForm`]: @api/rocket/request/struct.LenientForm.html #### Field Renaming @@ -629,14 +629,14 @@ struct Person { } ``` -The [forms validation](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/form_validation) -and [forms kitchen sink](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/form_kitchen_sink) +The [forms validation](@example/form_validation) +and [forms kitchen sink](@example/form_kitchen_sink) examples on GitHub provide further illustrations. ### JSON Handling JSON data is no harder: simply use the -[`Json`](https://api.rocket.rs/rocket_contrib/struct.Json.html) type: +[`Json`](@api/rocket_contrib/struct.Json.html) type: ```rust #[derive(Deserialize)] @@ -653,13 +653,13 @@ The only condition is that the generic type in `Json` implements the `Deserialize` trait from [Serde](https://github.com/serde-rs/json). See the [JSON example] on GitHub for a complete example. -[JSON example]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/json +[JSON example]: @example/json ### Streaming Sometimes you just want to handle incoming data directly. For example, you might want to stream the incoming data out to a file. Rocket makes this as simple as -possible via the [`Data`](https://api.rocket.rs/rocket/data/struct.Data.html) +possible via the [`Data`](@api/rocket/data/struct.Data.html) type: ```rust @@ -674,9 +674,7 @@ The route above accepts any `POST` request to the `/upload` path with `tmp/upload.txt`, and the number of bytes written is returned as a plain text response if the upload succeeds. If the upload fails, an error response is returned. The handler above is complete. It really is that simple! See the -[GitHub example -code](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/raw_upload) -for the full crate. +[GitHub example code](@example/raw_upload) for the full crate. ## Query Strings @@ -731,14 +729,14 @@ fn new(task: Option) { ... } For a concrete illustration on how to handle query parameters, see [the `query_params` -example](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/query_params). +example](@example/query_params). ## Error Catchers Routing may fail for a variety of reasons. These include: * A [request guard](#request-guards) returns `Failure`. - * A handler returns a [`Responder`](/guide/responses/#responder) that fails. + * A handler returns a [`Responder`](../responses/#responder) that fails. * No matching route was found. If any of these conditions occur, Rocket returns an error to the client. To do @@ -775,8 +773,8 @@ looks like: rocket::ignite().register(catchers![not_found]) ``` -Unlike route request handlers, catchers take exactly zero or one parameters. If -the catcher takes a parameter, it must be of type -[`&Request`](https://api.rocket.rs/rocket/struct.Request.html) The [error -catcher example](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/errors) -on GitHub illustrates their use in full. +Unlike route request handlers, catchers take exactly zero or one parameter. If +the catcher takes a parameter, it must be of type [`&Request`] The [error +catcher example](@example/errors) on GitHub illustrates their use in full. + +[`&Request]: @api/rocket/struct.Request.html diff --git a/site/guide/responses.md b/site/guide/5-responses.md similarity index 81% rename from site/guide/responses.md rename to site/guide/5-responses.md index c9b02909..e2725e42 100644 --- a/site/guide/responses.md +++ b/site/guide/5-responses.md @@ -6,7 +6,7 @@ trait can be returned, including your own. In this section, we describe the `Responder` trait as well as several useful `Responder`s provided by Rocket. We'll also briefly discuss how to implement your own `Responder`. -[`Responder`]: https://api.rocket.rs/rocket/response/trait.Responder.html +[`Responder`]: @api/rocket/response/trait.Responder.html ## Responder @@ -17,7 +17,7 @@ decides which to use. For instance, `String` uses a fixed-sized body, while `File` uses a streamed response. Responders may dynamically adjust their responses according to the incoming `Request` they are responding to. -[`Response`]: https://api.rocket.rs/rocket/response/struct.Response.html +[`Response`]: @api/rocket/response/struct.Response.html ### Wrapping @@ -31,10 +31,9 @@ struct WrappingResponder(R); A wrapping responder modifies the response returned by `R` before responding with that same response. For instance, Rocket provides `Responder`s in the -[`status` module](https://api.rocket.rs/rocket/response/status/index.html) that -override the status code of the wrapped `Responder`. As an example, the -[`Accepted`] type sets the status to `202 - Accepted`. It can be used as -follows: +[`status` module](@api/rocket/response/status/) that override the status code of +the wrapped `Responder`. As an example, the [`Accepted`] type sets the status to +`202 - Accepted`. It can be used as follows: ```rust use rocket::response::status; @@ -45,10 +44,10 @@ fn new(id: usize) -> status::Accepted { } ``` -Similarly, the types in the [`content` -module](https://api.rocket.rs/rocket/response/content/index.html) can be used to -override the Content-Type of a response. For instance, to set the Content-Type -of `&'static str` to JSON, you can use the [`content::Json`] type as follows: +Similarly, the types in the [`content` module](@api/rocket/response/content/) +can be used to override the Content-Type of a response. For instance, to set the +Content-Type of `&'static str` to JSON, you can use the [`content::Json`] type +as follows: ```rust use rocket::response::content; @@ -59,14 +58,14 @@ fn json() -> content::Json<&'static str> { } ``` -[`Accepted`]: https://api.rocket.rs/rocket/response/status/struct.Accepted.html -[`content::Json`]: https://api.rocket.rs/rocket/response/content/struct.Json.html +[`Accepted`]: @api/rocket/response/status/struct.Accepted.html +[`content::Json`]: @api/rocket/response/content/struct.Json.html ### Errors Responders may fail; they need not _always_ generate a response. Instead, they can return an `Err` with a given status code. When this happens, Rocket forwards -the request to the [error catcher](/guide/requests/#error-catchers) for the +the request to the [error catcher](../requests/#error-catchers) for the given status code. If an error catcher has been registered for the given status code, Rocket will @@ -78,7 +77,7 @@ for a custom status code, Rocket uses the **500** error catcher to return a response. While not encouraged, you can also forward a request to a catcher manually by -using the [`Failure`](https://api.rocket.rs/rocket/response/struct.Failure.html) +using the [`Failure`](@api/rocket/response/struct.Failure.html) type. For instance, to forward to the catcher for **406 - Not Acceptable**, you would write: @@ -181,13 +180,13 @@ many of these responders in the [`response`] module. Among these are: * [`status`] - Contains types that override the status code of a response. * [`Flash`] - Sets a "flash" cookie that is removed when accessed. -[`status`]: https://api.rocket.rs/rocket/response/status/index.html -[`response`]: https://api.rocket.rs/rocket/response/index.html -[`NamedFile`]: https://api.rocket.rs/rocket/response/struct.NamedFile.html -[`Content`]: https://api.rocket.rs/rocket/response/struct.Content.html -[`Redirect`]: https://api.rocket.rs/rocket/response/struct.Redirect.html -[`Stream`]: https://api.rocket.rs/rocket/response/struct.Stream.html -[`Flash`]: https://api.rocket.rs/rocket/response/struct.Flash.html +[`status`]: @api/rocket/response/status/ +[`response`]: @api/rocket/response/ +[`NamedFile`]: @api/rocket/response/struct.NamedFile.html +[`Content`]: @api/rocket/response/struct.Content.html +[`Redirect`]: @api/rocket/response/struct.Redirect.html +[`Stream`]: @api/rocket/response/struct.Stream.html +[`Flash`]: @api/rocket/response/struct.Flash.html ### Streaming @@ -205,7 +204,7 @@ fn stream() -> io::Result> { ``` -[`rocket_contrib`]: https://api.rocket.rs/rocket_contrib/index.html +[`rocket_contrib`]: @api/rocket_contrib/ ### JSON @@ -233,10 +232,10 @@ fails, a **500 - Internal Server Error** is returned. The [JSON example on GitHub] provides further illustration. -[`JSON`]: https://api.rocket.rs/rocket_contrib/struct.Json.html +[`JSON`]: @api/rocket_contrib/struct.Json.html [`Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html [`serde`]: https://docs.serde.rs/serde/ -[JSON example on GitHub]: https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/json +[JSON example on GitHub]: @example/json ### Templates @@ -269,7 +268,7 @@ This means that you don't need to rebuild your application to observe template changes: simply refresh! In release builds, reloading is disabled. For templates to be properly registered, the template fairing must be attached -to the instance of Rocket. The [Fairings](/guide/fairings) sections of the guide +to the instance of Rocket. The [Fairings](../fairings) sections of the guide provides more information on fairings. To attach the template fairing, simply call `.attach(Template::fairing())` on an instance of `Rocket` as follows: @@ -283,9 +282,8 @@ fn main() { The [`Template`] API documentation contains more information about templates, including how to customize a template engine to add custom helpers and filters. -The [Handlebars Templates example on -GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/handlebars_templates) -is a fully composed application that makes use of Handlebars templates. +The [Handlebars Templates example on GitHub](@example/handlebars_templates) is a +fully composed application that makes use of Handlebars templates. -[`Template`]: https://api.rocket.rs/rocket_contrib/struct.Template.html -[configurable]: /guide/configuration/#extras +[`Template`]: @api/rocket_contrib/struct.Template.html +[configurable]: ../configuration/#extras diff --git a/site/guide/state.md b/site/guide/6-state.md similarity index 91% rename from site/guide/state.md rename to site/guide/6-state.md index b9dce5b8..662d8016 100644 --- a/site/guide/state.md +++ b/site/guide/6-state.md @@ -22,7 +22,7 @@ The process for using managed state is simple: ### Adding State To instruct Rocket to manage state for your application, call the -[`manage`](https://api.rocket.rs/rocket/struct.Rocket.html#method.manage) method +[`manage`](@api/rocket/struct.Rocket.html#method.manage) method on an instance of `Rocket`. For example, to ask Rocket to manage a `HitCount` structure with an internal `AtomicUsize` with an initial value of `0`, we can write the following: @@ -48,8 +48,8 @@ rocket::ignite() ### Retrieving State State that is being managed by Rocket can be retrieved via the -[`State`](https://api.rocket.rs/rocket/struct.State.html) type: a [request -guard](/guide/requests/#request-guards) for managed state. To use the request +[`State`](@api/rocket/struct.State.html) type: a [request +guard](../requests/#request-guards) for managed state. To use the request guard, add a `State` type to any request handler, where `T` is the type of the managed state. For example, we can retrieve and respond with the current `HitCount` in a `count` route as follows: @@ -74,11 +74,9 @@ the offending route. Instead, Rocket will log an error message and return a **500** error to the client. You can find a complete example using the `HitCount` structure in the [state -example on -GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/state) and -learn more about the [`manage` -method](https://api.rocket.rs/rocket/struct.Rocket.html#method.manage) and -[`State` type](https://api.rocket.rs/rocket/struct.State.html) in the API docs. +example on GitHub](@example/state) and learn more about the [`manage` +method](@api/rocket/struct.Rocket.html#method.manage) and [`State` +type](@api/rocket/struct.State.html) in the API docs. ### Within Guards @@ -94,7 +92,7 @@ fn from_request(req: &'a Request<'r>) -> request::Outcome { } ``` -[`Request::guard()`]: https://api.rocket.rs/rocket/struct.Request.html#method.guard +[`Request::guard()`]: @api/rocket/struct.Request.html#method.guard ### Request-Local State @@ -142,8 +140,8 @@ request-local state to cache expensive authentication and authorization computations, and the [`Fairing`] documentation, which uses request-local state to implement request timing. -[`FromRequest`]: https://api.rocket.rs/rocket/request/trait.FromRequest.htmll#request-local-state -[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#request-local-state +[`FromRequest`]: @api/rocket/request/trait.FromRequest.htmll#request-local-state +[`Fairing`]: @api/rocket/fairing/trait.Fairing.html#request-local-state ## Databases @@ -255,4 +253,4 @@ fn get_logs(conn: LogsDbConn, id: usize) -> Result { For more on Rocket's built-in database support, see the [`rocket_contrib::databases`] module documentation. -[`rocket_contrib::databases`]: https://api.rocket.rs/rocket_contrib/databases/index.html +[`rocket_contrib::databases`]: @api/rocket_contrib/databases/index.html diff --git a/site/guide/fairings.md b/site/guide/7-fairings.md similarity index 84% rename from site/guide/fairings.md rename to site/guide/7-fairings.md index 75ff67ca..1879be9e 100644 --- a/site/guide/fairings.md +++ b/site/guide/7-fairings.md @@ -33,10 +33,10 @@ _unless_ the authentication or authorization applies to all or most of the application. On the other hand, you _should_ use a fairing to record timing and usage statistics or to enforce global security policies. -[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html -[request guard]: /guide/requests/#request-guards -[request guards]: /guide/requests/#request-guards -[data guards]: /guide/requests/#body-data +[`Fairing`]: @api/rocket/fairing/trait.Fairing.html +[request guard]: ../requests/#request-guards +[request guards]: ../requests/#request-guards +[data guards]: ../requests/#body-data ### Attaching @@ -52,8 +52,8 @@ rocket::ignite() .launch(); ``` -[`attach`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.attach -[`Rocket`]: https://api.rocket.rs/rocket/struct.Rocket.html +[`attach`]: @api/rocket/struct.Rocket.html#method.attach +[`Rocket`]: @api/rocket/struct.Rocket.html Fairings are executed in the order in which they are attached: the first attached fairing has its callbacks executed before all others. Because fairing @@ -68,12 +68,11 @@ events is described below: * **Attach (`on_attach`)** An attach callback is called when a fairing is first attached via the - [`attach`](https://api.rocket.rs/rocket/struct.Rocket.html#method.attach) - method. An attach callback can arbitrarily modify the `Rocket` instance - being constructed and optionally abort launch. Attach fairings are commonly - used to parse and validate configuration values, aborting on bad - configurations, and inserting the parsed value into managed state for later - retrieval. + [`attach`](@api/rocket/struct.Rocket.html#method.attach) method. An attach + callback can arbitrarily modify the `Rocket` instance being constructed and + optionally abort launch. Attach fairings are commonly used to parse and + validate configuration values, aborting on bad configurations, and inserting + the parsed value into managed state for later retrieval. * **Launch (`on_launch`)** @@ -108,12 +107,12 @@ fairing and determine the set of callbacks the fairing is registering for. A [`on_launch`], [`on_request`], and [`on_response`]. Each callback has a default implementation that does absolutely nothing. -[`Info`]: https://api.rocket.rs/rocket/fairing/struct.Info.html -[`info`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#tymethod.info -[`on_attach`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_attach -[`on_launch`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_launch -[`on_request`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_request -[`on_response`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html#method.on_response +[`Info`]: @api/rocket/fairing/struct.Info.html +[`info`]: @api/rocket/fairing/trait.Fairing.html#tymethod.info +[`on_attach`]: @api/rocket/fairing/trait.Fairing.html#method.on_attach +[`on_launch`]: @api/rocket/fairing/trait.Fairing.html#method.on_launch +[`on_request`]: @api/rocket/fairing/trait.Fairing.html#method.on_request +[`on_response`]: @api/rocket/fairing/trait.Fairing.html#method.on_response ### Requirements @@ -182,8 +181,7 @@ impl Fairing for Counter { ``` For brevity, imports are not shown. The complete example can be found in the -[`Fairing` -documentation](https://api.rocket.rs/rocket/fairing/trait.Fairing.html#example). +[`Fairing` documentation](@api/rocket/fairing/trait.Fairing.html#example). ## Ad-Hoc Fairings @@ -212,4 +210,4 @@ rocket::ignite() })); ``` -[`AdHoc`]: https://api.rocket.rs/rocket/fairing/enum.AdHoc.html +[`AdHoc`]: @api/rocket/fairing/enum.AdHoc.html diff --git a/site/guide/testing.md b/site/guide/8-testing.md similarity index 85% rename from site/guide/testing.md rename to site/guide/8-testing.md index cfda1777..1d7c1ac7 100644 --- a/site/guide/testing.md +++ b/site/guide/8-testing.md @@ -36,10 +36,10 @@ instance. Usage is straightforward: let response = req.dispatch(); ``` -[`local`]: https://api.rocket.rs/rocket/local/index.html -[`Client`]: https://api.rocket.rs/rocket/local/struct.Client.html -[`LocalRequest`]: https://api.rocket.rs/rocket/local/struct.LocalRequest.html -[`Rocket`]: https://api.rocket.rs/rocket/struct.Rocket.html +[`local`]: @api/rocket/local/index.html +[`Client`]: @api/rocket/local/struct.Client.html +[`LocalRequest`]: @api/rocket/local/struct.LocalRequest.html +[`Rocket`]: @api/rocket/struct.Rocket.html ## Validating Responses @@ -57,13 +57,13 @@ a few below: * [`body_string`]: returns the body data as a `String`. * [`body_bytes`]: returns the body data as a `Vec`. -[`LocalResponse`]: https://api.rocket.rs/rocket/local/struct.LocalResponse.html -[`Response`]: https://api.rocket.rs/rocket/struct.Response.html -[`status`]: https://api.rocket.rs/rocket/struct.Response.html#method.status -[`content_type`]: https://api.rocket.rs/rocket/struct.Response.html#method.content_type -[`headers`]: https://api.rocket.rs/rocket/struct.Response.html#method.headers -[`body_string`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_string -[`body_bytes`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_bytes +[`LocalResponse`]: @api/rocket/local/struct.LocalResponse.html +[`Response`]: @api/rocket/struct.Response.html +[`status`]: @api/rocket/struct.Response.html#method.status +[`content_type`]: @api/rocket/struct.Response.html#method.content_type +[`headers`]: @api/rocket/struct.Response.html#method.headers +[`body_string`]: @api/rocket/struct.Response.html#method.body_string +[`body_bytes`]: @api/rocket/struct.Response.html#method.body_bytes These methods are typically used in combination with the `assert_eq!` or `assert!` macros as follows: @@ -178,8 +178,7 @@ mod test { ``` The tests can be run with `cargo test`. You can find the full source code to -[this example on -GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.4.0-dev/examples/testing). +[this example on GitHub](@example/testing). ## Codegen Debug diff --git a/site/guide/configuration.md b/site/guide/9-configuration.md similarity index 96% rename from site/guide/configuration.md rename to site/guide/9-configuration.md index 73c07a2b..f3bcfb56 100644 --- a/site/guide/configuration.md +++ b/site/guide/9-configuration.md @@ -131,8 +131,8 @@ incoming JSON data. You should use the `limits` parameter for your application's data limits as well. Data limits can be retrieved at runtime via the [`Request::limits()`] method. -[`Request::limits()`]: https://api.rocket.rs/rocket/struct.Request.html#method.limits -[`Json`]: https://api.rocket.rs/rocket_contrib/struct.Json.html#incoming-data-limits +[`Request::limits()`]: @api/rocket/struct.Request.html#method.limits +[`Json`]: @api/rocket_contrib/struct.Json.html#incoming-data-limits ## Extras @@ -140,7 +140,7 @@ In addition to overriding default configuration parameters, a configuration file can also define values for any number of _extra_ configuration parameters. While these parameters aren't used by Rocket directly, other libraries, or your own application, can use them as they wish. As an example, the -[Template](https://api.rocket.rs/rocket_contrib/struct.Template.html) type +[Template](@api/rocket_contrib/struct.Template.html) type accepts a value for the `template_dir` configuration parameter. The parameter can be set in `Rocket.toml` as follows: @@ -167,8 +167,8 @@ To retrieve a custom, extra configuration parameter in your application, we recommend using an [ad-hoc attach fairing] in combination with [managed state]. For example, if your application makes use of a custom `assets_dir` parameter: -[ad-hoc attach fairing]: /guide/fairings/#ad-hoc-fairings -[managed state]: /guide/state/#managed-state +[ad-hoc attach fairing]: ../fairings/#ad-hoc-fairings +[managed state]: ../state/#managed-state ```toml [development] diff --git a/site/guide.md b/site/guide/index.md similarity index 98% rename from site/guide.md rename to site/guide/index.md index ae51f319..9a10e0c2 100644 --- a/site/guide.md +++ b/site/guide/index.md @@ -6,7 +6,7 @@ This is the official guide. It is designed to serve as a starting point to writing web applications with Rocket and Rust. The guide is also designed to be a reference for experienced Rocket developers. This guide is conversational in tone. For concise and purely technical documentation, see the [API -documentation](https://api.rocket.rs). +documentation](@api). The guide is split into several sections, each with a focus on a different aspect of Rocket. The sections are: diff --git a/site/index.toml b/site/index.toml index 163f8927..912fb17a 100644 --- a/site/index.toml +++ b/site/index.toml @@ -12,21 +12,21 @@ title = "Type Safe" text = "From request to response Rocket ensures that your types mean something." image = "helmet" button = "Learn More" -url = "/overview/#how-rocket-works" +url = "overview/#how-rocket-works" [[top_features]] title = "Boilerplate Free" text = "Spend your time writing code that really matters, and let Rocket generate the rest." image = "robot-free" button = "See Examples" -url = "/overview/#anatomy-of-a-rocket-application" +url = "overview/#anatomy-of-a-rocket-application" [[top_features]] title = "Easy To Use" text = "Rocket makes extensive use of Rust's code generation tools to provide a clean API." image = "sun" button = "Get Started" -url = "/guide" +url = "guide" margin = 2 [[top_features]] @@ -34,7 +34,7 @@ title = "Extensible" text = "Easily create your own primitives that any Rocket application can use." image = "telescope" button = "See How" -url = "/overview/#anatomy-of-a-rocket-application" +url = "overview/#anatomy-of-a-rocket-application" margin = 9 ############################################################################### @@ -134,7 +134,7 @@ text = ''' title = 'Templating' text = "Rocket makes rendering templates a breeze with built-in templating support." image = 'templating-icon' -url = '/guide/responses/#templates' +url = 'guide/responses/#templates' button = 'Learn More' color = 'blue' @@ -142,7 +142,7 @@ color = 'blue' title = 'Cookies' text = "View, add, or remove cookies, with or without encryption, without hassle." image = 'cookies-icon' -url = '/guide/requests/#cookies' +url = 'guide/requests/#cookies' button = 'Learn More' color = 'purple' margin = -6 @@ -151,7 +151,7 @@ margin = -6 title = 'Streams' text = "Rocket streams all incoming and outgoing data, so size isn't a concern." image = 'streams-icon' -url = '/guide/requests/#streaming' +url = 'guide/requests/#streaming' button = 'Learn More' color = 'red' margin = -29 @@ -160,7 +160,7 @@ margin = -29 title = 'Config Environments' text = "Configure your application your way for development, staging, and production." image = 'config-icon' -url = '/guide/configuration/#environment' +url = 'guide/configuration/#environment' button = 'Learn More' color = 'yellow' margin = -3 @@ -169,7 +169,7 @@ margin = -3 title = 'Query Strings' text = "Handling query strings and parameters is type-safe and easy in Rocket." image = 'query-icon' -url = '/guide/requests/#query-strings' +url = 'guide/requests/#query-strings' button = 'Learn More' color = 'orange' margin = -3 @@ -178,7 +178,7 @@ margin = -3 title = 'Testing Library' text = "Unit test your applications with ease using the built-in testing library." image = 'testing-icon' -url = '/guide/testing#testing' +url = 'guide/testing#testing' button = 'Learn More' color = 'green' diff --git a/site/news/2017-02-06-version-0.2.md b/site/news/2017-02-06-version-0.2.md index 0e2ebb93..31aa3b6a 100644 --- a/site/news/2017-02-06-version-0.2.md +++ b/site/news/2017-02-06-version-0.2.md @@ -46,8 +46,8 @@ state's type in the function signature. It works in two easy steps: value passed into `manage`. Rocket takes care of the rest! `State` works through Rocket's [request -guards](/guide/requests/#request-guards). You can call `manage` any number of -times, as long as each call corresponds to a value of a different type. +guards](../../guide/requests/#request-guards). You can call `manage` any number +of times, as long as each call corresponds to a value of a different type. As a simple example, consider the following "hit counter" example application: @@ -110,16 +110,15 @@ help: maybe add a call to 'manage' here? | ^^^^^^^^^^^^^^^^ ``` -You can read more about managed state in the [guide](/guide/state/), the API -docs for -[manage](https://api.rocket.rs/rocket/struct.Rocket.html#method.manage), and the -API docs for [State](https://api.rocket.rs/rocket/struct.State.html). +You can read more about managed state in the [guide](../../guide/state/), the +API docs for [manage](@api/rocket/struct.Rocket.html#method.manage), and the API +docs for [State](@api/rocket/struct.State.html). ### Unmounted Routes Lint A common mistake that new Rocketeers make is forgetting to -[mount](/guide/overview/#mounting) declared routes. In Rocket v0.2, Rocket adds -a _lint_ that results in a compile-time warning for unmounted routes. As a +[mount](../../guide/overview/#mounting) declared routes. In Rocket v0.2, Rocket +adds a _lint_ that results in a compile-time warning for unmounted routes. As a simple illustration, consider the canonical "Hello, world!" Rocket application below, and note that we've forgotten to mount the `hello` route: @@ -157,8 +156,7 @@ help: maybe add a call to 'mount' here? The lint can be disabled selectively per route by adding an `#[allow(unmounted_route)]` annotation to a given route declaration. It can also be disabled globally by adding `#![allow(unmounted_route)]`. You can read more -about this lint in the [codegen -documentation](https://api.rocket.rs/rocket_codegen/index.html). +about this lint in the [codegen documentation](@api/rocket_codegen/index.html). ### Configuration via Environment Variables @@ -176,7 +174,7 @@ Configuration parameters set via environment variables take precedence over parameters set via the `Rocket.toml` configuration file. Note that _any_ parameter can be set via an environment variable, include _extras_. For more about configuration in Rocket, see the [configuration section of the -guide](/guide/overview/#configuration). +guide](../../guide/overview/#configuration). ### And Plenty More! @@ -392,5 +390,5 @@ contributing! Not already using Rocket? Rocket is extensively documented, making it easy for you to start writing your web applications in Rocket! See the -[overview](/overview) or start writing code immediately by reading through [the -guide](/guide). +[overview](../../overview) or start writing code immediately by reading through +[the guide](../../guide). diff --git a/site/news/2017-07-14-version-0.3.md b/site/news/2017-07-14-version-0.3.md index ff6b36cc..f89ce8b2 100644 --- a/site/news/2017-07-14-version-0.3.md +++ b/site/news/2017-07-14-version-0.3.md @@ -21,8 +21,8 @@ sacrificing flexibility or type safety. All with minimal code. Not already using Rocket? Join the thousands of users and dozens of companies happily using Rocket today! Rocket's extensive documentation makes it easy. Get -started now by [reading through the guide](/guide) or learning more from [the -overview](/overview). +started now by [reading through the guide](../../guide) or learning more from +[the overview](../../overview). ## What's New? @@ -61,7 +61,7 @@ limitations and abilities, and includes implementation examples. I encourage you to experiment with fairings and report your experiences. As always, feedback is instrumental in solidifying a robust design. -[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html +[`Fairing`]: @api/rocket/fairing/trait.Fairing.html [fairings guide]: /guide/fairings ### Native TLS Support @@ -126,10 +126,10 @@ automatically generates a fresh key at launch. For more details on private cookies, see the [private cookies] section of the guide. -[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html -[`get_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.get_private -[`add_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.add_private -[`remove_private`]: https://api.rocket.rs/rocket/http/enum.Cookies.html#method.remove_private +[`Cookies`]: @api/rocket/http/enum.Cookies.html +[`get_private`]: @api/rocket/http/enum.Cookies.html#method.get_private +[`add_private`]: @api/rocket/http/enum.Cookies.html#method.add_private +[`remove_private`]: @api/rocket/http/enum.Cookies.html#method.remove_private [private cookies]: /guide/requests/#private-cookies ### Form Field Naming @@ -163,9 +163,9 @@ struct External { Rocket will automatically match the form field named "type" to the structure field named `api_type`. For more details on form field naming, see the [field -renaming](/guide/requests/#field-renaming) section of the guide. +renaming](../../guide/requests/#field-renaming) section of the guide. -[`FromForm`]: https://api.rocket.rs/rocket/request/trait.FromForm.html +[`FromForm`]: @api/rocket/request/trait.FromForm.html ### And Plenty More! @@ -189,7 +189,7 @@ following new features: * [`Response::content_type()`] was added to retrieve the Content-Type header of a response. * Data limits on incoming data are [now - configurable](/guide/configuration/#data-limits). + configurable](../../guide/configuration/#data-limits). * [`Request::limits()`] was added to retrieve incoming data limits. * Responders may dynamically adjust their response based on the incoming request. @@ -211,28 +211,28 @@ following new features: * The [`NotFound`] responder was added for simple **404** response construction. -[`MsgPack`]: https://api.rocket.rs/rocket_contrib/struct.MsgPack.html -[`Rocket::launch()`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.launch -[`LaunchError`]: https://api.rocket.rs/rocket/error/struct.LaunchError.html -[Default rankings]: https://api.rocket.rs/rocket/struct.Route.html -[`&Route`]: https://api.rocket.rs/rocket/struct.Route.html -[`Route`]: https://api.rocket.rs/rocket/struct.Route.html -[`Accept`]: https://api.rocket.rs/rocket/http/struct.Accept.html -[`Request::accept()`]: https://api.rocket.rs/rocket/struct.Request.html#method.accept -[`contrib`]: https://api.rocket.rs/rocket_contrib/ -[`Rocket::routes()`]: https://api.rocket.rs/rocket/struct.Rocket.html#method.routes -[`Response::body_string()`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_string -[`Response::body_bytes()`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_bytes -[`Response::content_type()`]: https://api.rocket.rs/rocket/struct.Response.html#method.content_type -[`Request::guard()`]: https://api.rocket.rs/rocket/struct.Request.html#method.guard -[`Request::limits()`]: https://api.rocket.rs/rocket/struct.Request.html#method.limits -[`Request::route()`]: https://api.rocket.rs/rocket/struct.Request.html#method.route -[`Config`]: https://api.rocket.rs/rocket/struct.Config.html -[`Cookies`]: https://api.rocket.rs/rocket/http/enum.Cookies.html -[`Config::get_datetime()`]: https://api.rocket.rs/rocket/struct.Config.html#method.get_datetime -[`LenientForm`]: https://api.rocket.rs/rocket/request/struct.LenientForm.html -[configuration parameters]: https://api.rocket.rs/rocket/config/index.html#environment-variables -[`NotFound`]: https://api.rocket.rs/rocket/response/status/struct.NotFound.html +[`MsgPack`]: @api/rocket_contrib/struct.MsgPack.html +[`Rocket::launch()`]: @api/rocket/struct.Rocket.html#method.launch +[`LaunchError`]: @api/rocket/error/struct.LaunchError.html +[Default rankings]: @api/rocket/struct.Route.html +[`&Route`]: @api/rocket/struct.Route.html +[`Route`]: @api/rocket/struct.Route.html +[`Accept`]: @api/rocket/http/struct.Accept.html +[`Request::accept()`]: @api/rocket/struct.Request.html#method.accept +[`contrib`]: @api/rocket_contrib/ +[`Rocket::routes()`]: @api/rocket/struct.Rocket.html#method.routes +[`Response::body_string()`]: @api/rocket/struct.Response.html#method.body_string +[`Response::body_bytes()`]: @api/rocket/struct.Response.html#method.body_bytes +[`Response::content_type()`]: @api/rocket/struct.Response.html#method.content_type +[`Request::guard()`]: @api/rocket/struct.Request.html#method.guard +[`Request::limits()`]: @api/rocket/struct.Request.html#method.limits +[`Request::route()`]: @api/rocket/struct.Request.html#method.route +[`Config`]: @api/rocket/struct.Config.html +[`Cookies`]: @api/rocket/http/enum.Cookies.html +[`Config::get_datetime()`]: @api/rocket/struct.Config.html#method.get_datetime +[`LenientForm`]: @api/rocket/request/struct.LenientForm.html +[configuration parameters]: @api/rocket/config/index.html#environment-variables +[`NotFound`]: @api/rocket/response/status/struct.NotFound.html ## Breaking Changes @@ -267,9 +267,9 @@ In addition to new features, Rocket saw the following improvements: * The format of a request is always logged when available. [`yansi`]: https://crates.io/crates/yansi -[`Request`]: https://api.rocket.rs/rocket/struct.Request.html -[`State`]: https://api.rocket.rs/rocket/struct.State.html -[`Config`]: https://api.rocket.rs/rocket/struct.Config.html +[`Request`]: @api/rocket/struct.Request.html +[`State`]: @api/rocket/struct.State.html +[`Config`]: @api/rocket/struct.Config.html ## What's Next? diff --git a/site/news.toml b/site/news/index.toml similarity index 100% rename from site/news.toml rename to site/news/index.toml diff --git a/site/overview.toml b/site/overview.toml index e4d7ba0a..a0b8fcb0 100644 --- a/site/overview.toml +++ b/site/overview.toml @@ -47,7 +47,7 @@ Each dynamic parameter (`name` and `age`) must have a type, here `&str` and `u8`, respectively. Rocket will attempt to parse the string in the parameter's position in the path into that type. The route will only be called if parsing succeeds. To parse the string, Rocket uses the -[FromParam](https://api.rocket.rs/rocket/request/trait.FromParam.html) trait, +[FromParam](@api/rocket/request/trait.FromParam.html) trait, which you can implement for your own types! ''' @@ -55,7 +55,7 @@ which you can implement for your own types! name = "Handling Data" content = ''' Request body data is handled in a special way in Rocket: via the -[FromData](https://api.rocket.rs/rocket/data/trait.FromData.html) trait. Any +[FromData](@api/rocket/data/trait.FromData.html) trait. Any type that implements `FromData` can be derived from incoming body data. To tell Rocket that you're expecting request body data, the `data` route argument is used with the name of the parameter in the request handler: @@ -69,13 +69,13 @@ fn login(user_form: Form) -> String { The `login` route above says that it expects `data` of type `Form` in the `user_form` parameter. The -[Form](https://api.rocket.rs/rocket/request/struct.Form.html) type is a built-in +[Form](@api/rocket/request/struct.Form.html) type is a built-in Rocket type that knows how to parse web forms into structures. Rocket will automatically attempt to parse the request body into the `Form` and call the `login` handler if parsing succeeds. Other built-in `FromData` types include -[`Data`](https://api.rocket.rs/rocket/struct.Data.html), -[`Json`](https://api.rocket.rs/rocket_contrib/struct.Json.html), and -[`Flash`](https://api.rocket.rs/rocket/response/struct.Flash.html) +[`Data`](@api/rocket/struct.Data.html), +[`Json`](@api/rocket_contrib/struct.Json.html), and +[`Flash`](@api/rocket/response/struct.Flash.html) ''' [[panels]] @@ -99,7 +99,7 @@ fn sensitive(key: ApiKey) -> &'static str { ... } `ApiKey` protects the `sensitive` handler from running incorrectly. In order for Rocket to call the `sensitive` handler, the `ApiKey` type needs to be derived through a -[FromRequest](https://api.rocket.rs/rocket/request/trait.FromRequest.html) +[FromRequest](@api/rocket/request/trait.FromRequest.html) implementation, which in this case, validates the API key header. Request guards are a powerful and unique Rocket concept; they centralize application policy and invariants through types. @@ -109,7 +109,7 @@ invariants through types. name = "Responders" content = ''' The return type of a request handler can be any type that implements -[Responder](https://api.rocket.rs/rocket/response/trait.Responder.html): +[Responder](@api/rocket/response/trait.Responder.html): ```rust #[get("/")] @@ -119,12 +119,12 @@ fn route() -> T { ... } Above, T must implement `Responder`. Rocket implements `Responder` for many of the standard library types including `&str`, `String`, `File`, `Option`, and `Result`. Rocket also implements custom responders such as -[Redirect](https://api.rocket.rs/rocket/response/struct.Redirect.html), -[Flash](https://api.rocket.rs/rocket/response/struct.Flash.html), and -[Template](https://api.rocket.rs/rocket_contrib/struct.Template.html). +[Redirect](@api/rocket/response/struct.Redirect.html), +[Flash](@api/rocket/response/struct.Flash.html), and +[Template](@api/rocket_contrib/struct.Template.html). The task of a `Responder` is to generate a -[`Response`](https://api.rocket.rs/rocket/response/struct.Response.html), if +[`Response`](@api/rocket/response/struct.Response.html), if possible. `Responder`s can fail with a status code. When they do, Rocket calls the corresponding error catcher, a `catch` route, which can be declared as follows: