From 70dcba36260479ec5dbf76c2aa2aa676f6619d0b Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Sat, 2 Mar 2024 00:08:04 -0800 Subject: [PATCH] Reorganize and upgrade markup in site docs. The guide is now in docs/guide. All other site assets are being migrated to a separate repository. The guide markup has been upgraded to take advantages of improvements in the static site generator used to build the Rocket website. --- README.md | 2 +- docs/guide/00-introduction.md | 2 +- docs/guide/01-quickstart.md | 5 +-- docs/guide/03-overview.md | 6 +-- docs/guide/04-requests.md | 76 +++++++++++++++++----------------- docs/guide/05-responses.md | 68 +++++++++++++++--------------- docs/guide/06-state.md | 18 ++++---- docs/guide/07-fairings.md | 24 +++++------ docs/guide/08-testing.md | 24 +++++------ docs/guide/09-configuration.md | 10 ++--- docs/guide/10-pastebin.md | 14 +++---- docs/guide/11-conclusion.md | 5 ++- docs/guide/index.md | 12 ++---- 13 files changed, 130 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index f5cc38cc..d240cd11 100644 --- a/README.md +++ b/README.md @@ -151,4 +151,4 @@ Rocket is licensed under either of the following, at your option: * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) -The Rocket site docs source is licensed under [separate terms](docs/LICENSE). +The Rocket site docs are licensed under [separate terms](docs/LICENSE). diff --git a/docs/guide/00-introduction.md b/docs/guide/00-introduction.md index f8879ca8..a93c43c1 100644 --- a/docs/guide/00-introduction.md +++ b/docs/guide/00-introduction.md @@ -2,7 +2,7 @@ Rocket is a web framework for Rust. If you'd like, you can think of Rocket as being a more flexible, friendly medley of [Rails](http://rubyonrails.org), -[Flask](http://flask.pocoo.org/), +[Flask](https://flask.palletsprojects.com/), [Bottle](http://bottlepy.org/docs/dev/index.html), and [Yesod](http://www.yesodweb.com/). We prefer to think of Rocket as something new. Rocket aims to be fast, easy, and flexible while offering guaranteed safety diff --git a/docs/guide/01-quickstart.md b/docs/guide/01-quickstart.md index 102d9031..bac4f107 100644 --- a/docs/guide/01-quickstart.md +++ b/docs/guide/01-quickstart.md @@ -3,8 +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](../getting-started) -section. +like extra guidance doing so, see [Getting Started]. ## Running Examples @@ -29,4 +28,4 @@ with `cargo run`. libraries. When copying the examples for your own use, you should modify the `Cargo.toml` files as explained in the [Getting Started] guide. -[Getting Started]: ../getting-started +[Getting Started]: ../getting-started/ diff --git a/docs/guide/03-overview.md b/docs/guide/03-overview.md index 7b9b691e..ab1d32f0 100644 --- a/docs/guide/03-overview.md +++ b/docs/guide/03-overview.md @@ -74,7 +74,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](../requests) section describes the available options for +[Requests](../requests/) section describes the available options for constructing routes. ## Mounting @@ -206,6 +206,6 @@ If we visit `localhost:8000/hello/world`, we see `Hello, world!`, exactly as we expected. A version of this example's complete crate, ready to `cargo run`, can be found -on [GitHub](@example/hello_world). You can find dozens of other complete +on [GitHub](@git/v0.4/examples/hello_world). You can find dozens of other complete examples, spanning all of Rocket's features, in the [GitHub examples -directory](@example/). +directory](@git/v0.4/examples/). diff --git a/docs/guide/04-requests.md b/docs/guide/04-requests.md index 1ed4199c..755f2238 100644 --- a/docs/guide/04-requests.md +++ b/docs/guide/04-requests.md @@ -30,7 +30,7 @@ validations. Rocket's code generation takes care of actually validating the properties. This section describes how to ask Rocket to validate against all of these properties and more. -[`route`]: @api/rocket/attr.route.html +[`route`]: @api/v0.4/rocket/attr.route.html ## Methods @@ -66,7 +66,7 @@ request contains a body of `Content-Type: application/x-www-form-urlencoded` and the form's **first** 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](@example/todo/static/index.html.tera#L47) makes use of this +The [todo example](@git/v0.4/examples/todo/static/index.html.tera#L47) makes use of this feature to submit `PUT` and `DELETE` requests from a web form. ## Dynamic Paths @@ -115,8 +115,8 @@ fn hello(name: String, age: u8, cool: bool) -> String { } ``` -[`FromParam`]: @api/rocket/request/trait.FromParam.html -[`FromParam` API docs]: @api/rocket/request/trait.FromParam.html +[`FromParam`]: @api/v0.4/rocket/request/trait.FromParam.html +[`FromParam` API docs]: @api/v0.4/rocket/request/trait.FromParam.html ! note: Rocket types _raw_ strings separately from decoded strings. @@ -135,7 +135,7 @@ fn hello(name: String, age: u8, cool: bool) -> String { potentially unsafe access to the string (`&RawStr`), or safe access to the string at the cost of an allocation (`String`). - [`RawStr`]: @api/rocket/http/struct.RawStr.html + [`RawStr`]: @api/v0.4/rocket/http/struct.RawStr.html ### Multiple Segments @@ -185,9 +185,9 @@ fn files(file: PathBuf) -> Option { `rocket.mount("/public", StaticFiles::from("/static"))` -[`rocket_contrib`]: @api/rocket_contrib/ -[`StaticFiles`]: @api/rocket_contrib/serve/struct.StaticFiles.html -[`FromSegments`]: @api/rocket/request/trait.FromSegments.html +[`rocket_contrib`]: @api/v0.4/rocket_contrib/ +[`StaticFiles`]: @api/v0.4/rocket_contrib/serve/struct.StaticFiles.html +[`FromSegments`]: @api/v0.4/rocket/request/trait.FromSegments.html ## Forwarding @@ -325,7 +325,7 @@ Any number of dynamic query segments are allowed. A query segment can be of any type, including your own, as long as the type implements the [`FromFormValue`] trait. -[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html +[`FromFormValue`]: @api/v0.4/rocket/request/trait.FromFormValue.html ### Optional Parameters @@ -362,7 +362,7 @@ value `false` if it is missing. The default value for a missing parameter can be customized for your own types that implement `FromFormValue` by implementing [`FromFormValue::default()`]. -[`FromFormValue::default()`]: @api/rocket/request/trait.FromFormValue.html#method.default +[`FromFormValue::default()`]: @api/v0.4/rocket/request/trait.FromFormValue.html#method.default ### Multiple Segments @@ -412,9 +412,9 @@ fn item(id: usize, user: Option>) { /* ... */ } ``` For more query handling examples, see [the `query_params` -example](@example/query_params). +example](@git/v0.4/examples/query_params). -[`FromQuery`]: @api/rocket/request/trait.FromQuery.html +[`FromQuery`]: @api/v0.4/rocket/request/trait.FromQuery.html ## Request Guards @@ -454,8 +454,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`]: @api/rocket/request/trait.FromRequest.html -[`Cookies`]: @api/rocket/http/enum.Cookies.html +[`FromRequest`]: @api/v0.4/rocket/request/trait.FromRequest.html +[`Cookies`]: @api/v0.4/rocket/http/enum.Cookies.html ### Custom Guards @@ -610,7 +610,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]: @example/cookies +[cookies example]: @git/v0.4/examples/cookies ### Private Cookies @@ -651,7 +651,7 @@ fn logout(mut cookies: Cookies) -> Flash { } ``` -[`Cookies::add()`]: @api/rocket/http/enum.Cookies.html#method.add +[`Cookies::add()`]: @api/v0.4/rocket/http/enum.Cookies.html#method.add Support for private cookies, which depends on the [`ring`] library, can be omitted at build time by disabling Rocket's default features, in-turn disabling @@ -680,12 +680,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](../configuration) +For more information on configuration, see the [Configuration](../configuration/) section of the guide. -[`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 +[`get_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.get_private +[`add_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.add_private +[`remove_private`]: @api/v0.4/rocket/http/enum.Cookies.html#method.remove_private ### One-At-A-Time @@ -819,7 +819,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()`]: @api/rocket/http/struct.ContentType.html#method.parse_flexible +[`ContentType::parse_flexible()`]: @api/v0.4/rocket/http/struct.ContentType.html#method.parse_flexible ## Body Data @@ -840,7 +840,7 @@ fn new(input: T) { /* .. */ } Any type that implements [`FromData`] is also known as _a data guard_. -[`FromData`]: @api/rocket/data/trait.FromData.html +[`FromData`]: @api/v0.4/rocket/data/trait.FromData.html ### Forms @@ -890,9 +890,9 @@ and `Result` types: fn new(task: Option>) { /* .. */ } ``` -[`Form`]: @api/rocket/request/struct.Form.html -[`FromForm`]: @api/rocket/request/trait.FromForm.html -[`FromFormValue`]: @api/rocket/request/trait.FromFormValue.html +[`Form`]: @api/v0.4/rocket/request/struct.Form.html +[`FromForm`]: @api/v0.4/rocket/request/trait.FromForm.html +[`FromFormValue`]: @api/v0.4/rocket/request/trait.FromFormValue.html #### Lenient Parsing @@ -932,7 +932,7 @@ struct Task { fn new(task: LenientForm) { /* .. */ } ``` -[`LenientForm`]: @api/rocket/request/struct.LenientForm.html +[`LenientForm`]: @api/v0.4/rocket/request/struct.LenientForm.html #### Field Renaming @@ -1034,13 +1034,13 @@ decorated enum. The implementation returns successfully when the form value matches, case insensitively, the stringified version of a variant's name, returning an instance of said variant. -The [form validation](@example/form_validation) and [form kitchen -sink](@example/form_kitchen_sink) examples provide further illustrations. +The [form validation](@git/v0.4/examples/form_validation) and [form kitchen +sink](@git/v0.4/examples/form_kitchen_sink) examples provide further illustrations. ### JSON Handling JSON data is no harder: simply use the -[`Json`](@api/rocket_contrib/json/struct.Json.html) type from +[`Json`](@api/v0.4/rocket_contrib/json/struct.Json.html) type from [`rocket_contrib`]: ```rust @@ -1067,13 +1067,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]: @example/json +[JSON example]: @git/v0.4/examples/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`](@api/rocket/data/struct.Data.html) +possible via the [`Data`](@api/v0.4/rocket/data/struct.Data.html) type: ```rust @@ -1094,7 +1094,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](@example/raw_upload) for the full crate. +[GitHub example code](@git/v0.4/examples/raw_upload) for the full crate. ! warning: You should _always_ set limits when reading incoming data. @@ -1175,10 +1175,10 @@ fn main() { 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. +catcher example](@git/v0.4/examples/errors) on GitHub illustrates their use in full. -[`catch`]: @api/rocket/attr.catch.html -[`register()`]: @api/rocket/struct.Rocket.html#method.register -[`mount()`]: @api/rocket/struct.Rocket.html#method.mount -[`catchers!`]: @api/rocket/macro.catchers.html -[`&Request`]: @api/rocket/struct.Request.html +[`catch`]: @api/v0.4/rocket/attr.catch.html +[`register()`]: @api/v0.4/rocket/struct.Rocket.html#method.register +[`mount()`]: @api/v0.4/rocket/struct.Rocket.html#method.mount +[`catchers!`]: @api/v0.4/rocket/macro.catchers.html +[`&Request`]: @api/v0.4/rocket/struct.Request.html diff --git a/docs/guide/05-responses.md b/docs/guide/05-responses.md index 94840a94..28058d51 100644 --- a/docs/guide/05-responses.md +++ b/docs/guide/05-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`]: @api/rocket/response/trait.Responder.html +[`Responder`]: @api/v0.4/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`]: @api/rocket/response/struct.Response.html +[`Response`]: @api/v0.4/rocket/response/struct.Response.html ### Wrapping @@ -31,7 +31,7 @@ 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](@api/rocket/response/status/) that override the status code of +[`status` module](@api/v0.4/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: @@ -48,7 +48,7 @@ fn new(id: usize) -> status::Accepted { } ``` -Similarly, the types in the [`content` module](@api/rocket/response/content/) +Similarly, the types in the [`content` module](@api/v0.4/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: @@ -67,8 +67,8 @@ fn json() -> content::Json<&'static str> { ! warning: This is _not_ the same as the [`Json`] in [`rocket_contrib`]! -[`Accepted`]: @api/rocket/response/status/struct.Accepted.html -[`content::Json`]: @api/rocket/response/content/struct.Json.html +[`Accepted`]: @api/v0.4/rocket/response/status/struct.Accepted.html +[`content::Json`]: @api/v0.4/rocket/response/content/struct.Json.html ### Errors @@ -163,7 +163,7 @@ simply including fields of these types. For more on using the `Responder` derive, see the [`Responder` derive] documentation. -[`Responder` derive]: @api/rocket/derive.Responder.html +[`Responder` derive]: @api/v0.4/rocket/derive.Responder.html ## Implementations @@ -291,14 +291,14 @@ library. Among these are: * [`MsgPack`] - Automatically serializes values into MessagePack. * [`Template`] - Renders a dynamic template using handlebars or Tera. -[`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 -[`MsgPack`]: @api/rocket_contrib/msgpack/struct.MsgPack.html +[`status`]: @api/v0.4/rocket/response/status/ +[`response`]: @api/v0.4/rocket/response/ +[`NamedFile`]: @api/v0.4/rocket/response/struct.NamedFile.html +[`Content`]: @api/v0.4/rocket/response/struct.Content.html +[`Redirect`]: @api/v0.4/rocket/response/struct.Redirect.html +[`Stream`]: @api/v0.4/rocket/response/struct.Stream.html +[`Flash`]: @api/v0.4/rocket/response/struct.Flash.html +[`MsgPack`]: @api/v0.4/rocket_contrib/msgpack/struct.MsgPack.html ### Streaming @@ -325,7 +325,7 @@ fn stream() -> Result, std::io::Error> { # } ``` -[`rocket_contrib`]: @api/rocket_contrib/ +[`rocket_contrib`]: @api/v0.4/rocket_contrib/ ### JSON @@ -362,10 +362,10 @@ fails, a **500 - Internal Server Error** is returned. The [JSON example on GitHub] provides further illustration. -[`Json`]: @api/rocket_contrib/json/struct.Json.html +[`Json`]: @api/v0.4/rocket_contrib/json/struct.Json.html [`Serialize`]: https://docs.serde.rs/serde/trait.Serialize.html [`serde`]: https://docs.serde.rs/serde/ -[JSON example on GitHub]: @example/json +[JSON example on GitHub]: @git/v0.4/examples/json ## Templates @@ -397,7 +397,7 @@ structs, `HashMaps`, and others. For a template to be renderable, it must first be registered. The `Template` fairing automatically registers all discoverable templates when attached. The -[Fairings](../fairings) sections of the guide provides more information on +[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: @@ -436,11 +436,11 @@ reloading is disabled. 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](@example/handlebars_templates) is a +The [Handlebars templates example](@git/v0.4/examples/handlebars_templates) is a fully composed application that makes use of Handlebars templates, while the -[Tera templates example](@example/tera_templates) does the same for Tera. +[Tera templates example](@git/v0.4/examples/tera_templates) does the same for Tera. -[`Template`]: @api/rocket_contrib/templates/struct.Template.html +[`Template`]: @api/v0.4/rocket_contrib/templates/struct.Template.html [configurable]: ../configuration/#extras ## Typed URIs @@ -654,15 +654,15 @@ uri!(person: id = 100, details = UserDetails { age: Some(20), nickname: "Bob".in See the [`FromUriParam`] documentation for further details. -[`Origin`]: @api/rocket/http/uri/struct.Origin.html -[`UriPart`]: @api/rocket/http/uri/trait.UriPart.html -[`Uri`]: @api/rocket/http/uri/enum.Uri.html -[`Redirect::to()`]: @api/rocket/response/struct.Redirect.html#method.to -[`uri!`]: @api/rocket/macro.uri.html -[`UriDisplay`]: @api/rocket/http/uri/trait.UriDisplay.html -[`FromUriParam`]: @api/rocket/http/uri/trait.FromUriParam.html -[`Path`]: @api/rocket/http/uri/enum.Path.html -[`Query`]: @api/rocket/http/uri/enum.Query.html -[`Ignorable`]: @api/rocket/http/uri/trait.Ignorable.html -[`UriDisplayPath`]: @api/rocket/derive.UriDisplayPath.html -[`UriDisplayQuery`]: @api/rocket/derive.UriDisplayQuery.html +[`Origin`]: @api/v0.4/rocket/http/uri/struct.Origin.html +[`UriPart`]: @api/v0.4/rocket/http/uri/trait.UriPart.html +[`Uri`]: @api/v0.4/rocket/http/uri/enum.Uri.html +[`Redirect::to()`]: @api/v0.4/rocket/response/struct.Redirect.html#method.to +[`uri!`]: @api/v0.4/rocket/macro.uri.html +[`UriDisplay`]: @api/v0.4/rocket/http/uri/trait.UriDisplay.html +[`FromUriParam`]: @api/v0.4/rocket/http/uri/trait.FromUriParam.html +[`Path`]: @api/v0.4/rocket/http/uri/enum.Path.html +[`Query`]: @api/v0.4/rocket/http/uri/enum.Query.html +[`Ignorable`]: @api/v0.4/rocket/http/uri/trait.Ignorable.html +[`UriDisplayPath`]: @api/v0.4/rocket/derive.UriDisplayPath.html +[`UriDisplayQuery`]: @api/v0.4/rocket/derive.UriDisplayQuery.html diff --git a/docs/guide/06-state.md b/docs/guide/06-state.md index f2bfd6b3..96600fdd 100644 --- a/docs/guide/06-state.md +++ b/docs/guide/06-state.md @@ -30,7 +30,7 @@ The process for using managed state is simple: ### Adding State To instruct Rocket to manage state for your application, call the -[`manage`](@api/rocket/struct.Rocket.html#method.manage) method +[`manage`](@api/v0.4/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: @@ -63,7 +63,7 @@ rocket::ignite() ### Retrieving State State that is being managed by Rocket can be retrieved via the -[`State`](@api/rocket/struct.State.html) type: a [request +[`State`](@api/v0.4/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 @@ -108,9 +108,9 @@ fn state(hit_count: State, config: State) { /* .. */ } **500** error to the client. You can find a complete example using the `HitCount` structure in the [state -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. +example on GitHub](@git/v0.4/examples/state) and learn more about the [`manage` +method](@api/v0.4/rocket/struct.Rocket.html#method.manage) and [`State` +type](@api/v0.4/rocket/struct.State.html) in the API docs. ### Within Guards @@ -142,7 +142,7 @@ impl<'a, 'r> FromRequest<'a, 'r> for T { } ``` -[`Request::guard()`]: @api/rocket/struct.Request.html#method.guard +[`Request::guard()`]: @api/v0.4/rocket/struct.Request.html#method.guard ## Request-Local State @@ -204,8 +204,8 @@ which uses request-local state to cache expensive authentication and authorization computations, and the [`Fairing`] documentation, which uses request-local state to implement request timing. -[`FromRequest` request-local state]: @api/rocket/request/trait.FromRequest.html#request-local-state -[`Fairing`]: @api/rocket/fairing/trait.Fairing.html#request-local-state +[`FromRequest` request-local state]: @api/v0.4/rocket/request/trait.FromRequest.html#request-local-state +[`Fairing`]: @api/v0.4/rocket/fairing/trait.Fairing.html#request-local-state ## Databases @@ -355,4 +355,4 @@ postgres = { version = "0.15", features = ["with-chrono"] } For more on Rocket's built-in database support, see the [`rocket_contrib::databases`] module documentation. -[`rocket_contrib::databases`]: @api/rocket_contrib/databases/index.html +[`rocket_contrib::databases`]: @api/v0.4/rocket_contrib/databases/index.html diff --git a/docs/guide/07-fairings.md b/docs/guide/07-fairings.md index eefa477a..5f59c9b3 100644 --- a/docs/guide/07-fairings.md +++ b/docs/guide/07-fairings.md @@ -36,7 +36,7 @@ that can be used to solve problems in a clean, composable, and robust manner. fairing to record timing and usage statistics or to enforce global security policies. -[`Fairing`]: @api/rocket/fairing/trait.Fairing.html +[`Fairing`]: @api/v0.4/rocket/fairing/trait.Fairing.html [request guard]: ../requests/#request-guards [request guards]: ../requests/#request-guards [data guards]: ../requests/#body-data @@ -60,8 +60,8 @@ rocket::ignite() # } ``` -[`attach`]: @api/rocket/struct.Rocket.html#method.attach -[`Rocket`]: @api/rocket/struct.Rocket.html +[`attach`]: @api/v0.4/rocket/struct.Rocket.html#method.attach +[`Rocket`]: @api/v0.4/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 @@ -76,7 +76,7 @@ events is described below: * **Attach (`on_attach`)** An attach callback is called when a fairing is first attached via the - [`attach`](@api/rocket/struct.Rocket.html#method.attach) method. An attach + [`attach`](@api/v0.4/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 @@ -115,12 +115,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`]: @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 +[`Info`]: @api/v0.4/rocket/fairing/struct.Info.html +[`info`]: @api/v0.4/rocket/fairing/trait.Fairing.html#tymethod.info +[`on_attach`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_attach +[`on_launch`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_launch +[`on_request`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_request +[`on_response`]: @api/v0.4/rocket/fairing/trait.Fairing.html#method.on_response ### Requirements @@ -196,7 +196,7 @@ impl Fairing for Counter { ``` The complete example can be found in the [`Fairing` -documentation](@api/rocket/fairing/trait.Fairing.html#example). +documentation](@api/v0.4/rocket/fairing/trait.Fairing.html#example). ## Ad-Hoc Fairings @@ -225,4 +225,4 @@ rocket::ignite() })); ``` -[`AdHoc`]: @api/rocket/fairing/struct.AdHoc.html +[`AdHoc`]: @api/v0.4/rocket/fairing/struct.AdHoc.html diff --git a/docs/guide/08-testing.md b/docs/guide/08-testing.md index 01532738..592e9b26 100644 --- a/docs/guide/08-testing.md +++ b/docs/guide/08-testing.md @@ -49,10 +49,10 @@ instance. Usage is straightforward: # let _ = response; ``` -[`local`]: @api/rocket/local/ -[`Client`]: @api/rocket/local/struct.Client.html -[`LocalRequest`]: @api/rocket/local/struct.LocalRequest.html -[`Rocket`]: @api/rocket/struct.Rocket.html +[`local`]: @api/v0.4/rocket/local/ +[`Client`]: @api/v0.4/rocket/local/struct.Client.html +[`LocalRequest`]: @api/v0.4/rocket/local/struct.LocalRequest.html +[`Rocket`]: @api/v0.4/rocket/struct.Rocket.html ## Validating Responses @@ -70,13 +70,13 @@ a few below: * [`body_string`]: returns the body data as a `String`. * [`body_bytes`]: returns the body data as a `Vec`. -[`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 +[`LocalResponse`]: @api/v0.4/rocket/local/struct.LocalResponse.html +[`Response`]: @api/v0.4/rocket/struct.Response.html +[`status`]: @api/v0.4/rocket/struct.Response.html#method.status +[`content_type`]: @api/v0.4/rocket/struct.Response.html#method.content_type +[`headers`]: @api/v0.4/rocket/struct.Response.html#method.headers +[`body_string`]: @api/v0.4/rocket/struct.Response.html#method.body_string +[`body_bytes`]: @api/v0.4/rocket/struct.Response.html#method.body_bytes These methods are typically used in combination with the `assert_eq!` or `assert!` macros as follows: @@ -252,7 +252,7 @@ mod test { ``` The tests can be run with `cargo test`. You can find the full source code to -[this example on GitHub](@example/testing). +[this example on GitHub](@git/v0.4/examples/testing). ## Codegen Debug diff --git a/docs/guide/09-configuration.md b/docs/guide/09-configuration.md index c5cc251f..24a8fb03 100644 --- a/docs/guide/09-configuration.md +++ b/docs/guide/09-configuration.md @@ -143,8 +143,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()`]: @api/rocket/struct.Request.html#method.limits -[`Json`]: @api/rocket_contrib/json/struct.Json.html#incoming-data-limits +[`Request::limits()`]: @api/v0.4/rocket/struct.Request.html#method.limits +[`Json`]: @api/v0.4/rocket_contrib/json/struct.Json.html#incoming-data-limits ## Extras @@ -152,7 +152,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](@api/rocket_contrib/templates/struct.Template.html) type +[Template](@api/v0.4/rocket_contrib/templates/struct.Template.html) type accepts a value for the `template_dir` configuration parameter. The parameter can be set in `Rocket.toml` as follows: @@ -292,8 +292,8 @@ all configuration from `Rocket.toml` or environment variables. In other words, using `rocket::custom()` results in `Rocket.toml` and environment variables being ignored. -[`rocket::custom()`]: @api/rocket/fn.custom.html -[`ConfigBuilder`]: @api/rocket/config/struct.ConfigBuilder.html +[`rocket::custom()`]: @api/v0.4/rocket/fn.custom.html +[`ConfigBuilder`]: @api/v0.4/rocket/config/struct.ConfigBuilder.html ## Configuring TLS diff --git a/docs/guide/10-pastebin.md b/docs/guide/10-pastebin.md index 7fa9b95d..b865db6c 100644 --- a/docs/guide/10-pastebin.md +++ b/docs/guide/10-pastebin.md @@ -104,7 +104,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](@api/rocket/response/trait.Responder.html). + trait](@api/v0.4/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: @@ -226,7 +226,7 @@ use rocket::Data; use rocket::http::RawStr; ``` -The [Data](@api/rocket/data/struct.Data.html) structure is key +The [Data](@api/v0.4/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. @@ -334,7 +334,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](@api/rocket/response/trait.Responder.html#provided-implementations) +[Responder](@api/v0.4/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. @@ -370,7 +370,7 @@ fn main() { ``` Unfortunately, there's a problem with this code. Can you spot the issue? The -[`RawStr`](@api/rocket/http/struct.RawStr.html) type should tip you off! +[`RawStr`](@api/v0.4/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 @@ -384,7 +384,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](@api/rocket/request/trait.FromParam.html) trait to +[FromParam](@api/v0.4/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: @@ -475,10 +475,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](@api/rocket/local/) to write unit tests for your + * Use the [`local` module](@api/v0.4/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](@example/pastebin). +GitHub](@git/v0.4/examples/pastebin). diff --git a/docs/guide/11-conclusion.md b/docs/guide/11-conclusion.md index 1229f5fd..78a47681 100644 --- a/docs/guide/11-conclusion.md +++ b/docs/guide/11-conclusion.md @@ -22,5 +22,6 @@ a client of your own. 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](@example) or the [Rocket source code](@github/core/lib/src). -Whatever you decide to do next, we hope you have a blast! +[Rocket examples](@git/v0.4/examples) or the [Rocket source +code](@git/v0.4/core/lib/src). Whatever you decide to do next, we hope you have +a blast! diff --git a/docs/guide/index.md b/docs/guide/index.md index f0f50e15..57215cff 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -6,7 +6,7 @@ This is the official guide for Rocket v0.4. 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 purely technical documentation with examples, see -the [API documentation](@api). +the [API documentation](@api/v0.4). The guide is split into several sections, each with a focus on a different aspect of Rocket. The sections are: @@ -33,12 +33,6 @@ aspect of Rocket. The sections are: ## Getting Help -The official community support channels are [`#rocket:mozilla.org`] on Matrix -and the bridged [`#rocket`] IRC channel on Freenode at `chat.freenode.net`. We -recommend joining us on [Matrix via Riot]. If your prefer IRC, you can join via -the [Kiwi IRC client] or a client of your own. +The official community support channels is [`#rocket:mozilla.org`] on Matrix. -[`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[`#rocket`]: https://kiwiirc.com/client/chat.freenode.net/#rocket -[Matrix via Riot]: https://chat.mozilla.org/#/room/#rocket:mozilla.org -[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket +[`#rocket:mozilla.org`]: @chat