Routing docs: core concepts (#122)

doc_examples/code_samples/guide/routing/Cargo.toml

@@ -0,0 +1,18 @@
+[workspace]
+members = [
+    "core_concepts",
+    "method_guards/any",
+    "method_guards/multi_method",
+    "method_guards/single_method",
+    "path_patterns/static",
+    "path_patterns/catch_all_parameter",
+    "path_patterns/multi_named_parameter",
+    "path_patterns/named_parameter",
+    "request_handlers/intro",
+    "request_handlers/error_handler",
+    "request_handlers/sync_or_async",
+]
+resolver = "2"
+
+[workspace.dependencies]
+pavex = { path = "../../../../libs/pavex" }

doc_examples/code_samples/guide/routing/core_concepts/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "core_concepts"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/core_concepts/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/greet", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/core_concepts/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/core_concepts/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/method_guards/any/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "any"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/method_guards/any/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::{router::ANY, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(ANY, "/greet", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/method_guards/any/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/method_guards/any/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/method_guards/multi_method/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "multi_method"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/method_guards/multi_method/src/blueprint.rs

@@ -0,0 +1,9 @@
+use pavex::blueprint::router::{GET, HEAD};
+use pavex::blueprint::Blueprint;
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET.or(HEAD), "/greet", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/method_guards/multi_method/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/method_guards/multi_method/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/method_guards/single_method/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "single_method"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/method_guards/single_method/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::{router::GET /* (1)! */, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/greet", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/method_guards/single_method/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/method_guards/single_method/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/path_patterns/catch_all_parameter/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "catch_all_parameter"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/path_patterns/catch_all_parameter/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/greet/*details", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/path_patterns/catch_all_parameter/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/path_patterns/catch_all_parameter/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/path_patterns/multi_named_parameter/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "multi_named_parameter"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/path_patterns/multi_named_parameter/src/blueprint.rs

@@ -0,0 +1,12 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(
+        GET,
+        "/greet/:first_name/:last_name",
+        f!(crate::routes::greet),
+    );
+    bp
+}

doc_examples/code_samples/guide/routing/path_patterns/multi_named_parameter/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/path_patterns/multi_named_parameter/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/path_patterns/named_parameter/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "named_parameter"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/path_patterns/named_parameter/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/greet/:name", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/path_patterns/named_parameter/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/path_patterns/named_parameter/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/path_patterns/static/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "static"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/path_patterns/static/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/greet", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/path_patterns/static/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/path_patterns/static/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    todo!()
+}

doc_examples/code_samples/guide/routing/request_handlers/error_handler/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "error_handler"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/request_handlers/error_handler/src/blueprint.rs

@@ -0,0 +1,9 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/greet", f!(crate::routes::greet))
+        .error_handler(f!(crate::error_handler::greet_error_handler));
+    bp
+}

doc_examples/code_samples/guide/routing/request_handlers/error_handler/src/error_handler.rs

@@ -0,0 +1,10 @@
+use pavex::response::Response;
+
+pub fn greet_error_handler(e: &GreetError) -> Response {
+    match e {
+        GreetError::InvalidName => Response::bad_request().set_typed_body("Invalid name."),
+        GreetError::DatabaseError => Response::internal_server_error()
+            .set_typed_body("Something went wrong, please retry later."),
+    }
+    .box_body()
+}

doc_examples/code_samples/guide/routing/request_handlers/error_handler/src/lib.rs

@@ -0,0 +1,3 @@
+pub mod blueprint;
+pub mod error_handler;
+pub mod routes;

doc_examples/code_samples/guide/routing/request_handlers/error_handler/src/routes.rs

@@ -0,0 +1,10 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> Result<StatusCode, GreetError> {
+    StatusCode::OK
+}
+
+pub enum GreetError {
+    DatabaseError,
+    InvalidName,
+}

doc_examples/code_samples/guide/routing/request_handlers/intro/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "intro"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/request_handlers/intro/src/blueprint.rs

@@ -0,0 +1,8 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/greet", f!(crate::routes::greet));
+    bp
+}

doc_examples/code_samples/guide/routing/request_handlers/intro/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/request_handlers/intro/src/routes.rs

@@ -0,0 +1,5 @@
+use pavex::http::StatusCode;
+
+pub fn greet() -> StatusCode {
+    StatusCode::OK
+}

doc_examples/code_samples/guide/routing/request_handlers/sync_or_async/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "sync_or_async"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+pavex = { workspace = true }

doc_examples/code_samples/guide/routing/request_handlers/sync_or_async/src/blueprint.rs

@@ -0,0 +1,9 @@
+use pavex::blueprint::{router::GET, Blueprint};
+use pavex::f;
+
+pub fn blueprint() -> Blueprint {
+    let mut bp = Blueprint::new();
+    bp.route(GET, "/async_greet", f!(crate::routes::async_greet));
+    bp.route(GET, "/sync_greet", f!(crate::routes::sync_greet));
+    bp
+}

doc_examples/code_samples/guide/routing/request_handlers/sync_or_async/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod blueprint;
+pub mod routes;

doc_examples/code_samples/guide/routing/request_handlers/sync_or_async/src/routes.rs

@@ -0,0 +1,9 @@
+use pavex::http::StatusCode;
+
+pub async fn async_greet() -> StatusCode {
+    StatusCode::OK
+}
+
+pub fn sync_greet() -> StatusCode {
+    StatusCode::OK
+}

docs/getting_started/index.md

@@ -40,7 +40,7 @@ rustup component add --toolchain nightly rust-docs-json
 All the code you'll be running (in production or otherwise) will be compiled with the stable toolchain. 
 Pavex relies on `nightly` to perform code generation and compile-time reflection—nothing else.
 
-## Pavex
+## Pavex CLI
 
 Pavex provides a command-line interface to scaffold new projects and work with existing ones.  
 To install it, execute the following command:

docs/getting_started/learning_paths.md

@@ -27,4 +27,4 @@ Once you feel comfortable enough with the language, you can start learning about
 ## I know some Rust, but I'm new to Pavex
 
 If you're already familiar with Rust, you can start learning about Pavex right away: head over to our 
-[Quickstart tutorial](quickstart.md) to learn about the core concepts of the framework.  
+[Quickstart tutorial](quickstart/index.md) to learn about the core concepts of the framework.