From 599f3c26e0da6985a275d8e2f392b6756a05fe44 Mon Sep 17 00:00:00 2001 From: Nikolay Kim Date: Mon, 27 Nov 2017 16:41:37 -0800 Subject: [PATCH] start working on guide --- .gitignore | 5 ++- .travis.yml | 9 +++++ build.rs | 2 +- examples/basic.rs | 6 ++-- guide/book.toml | 3 ++ guide/src/SUMMARY.md | 4 +++ guide/src/qs_1.md | 34 ++++++++++++++++++ guide/src/qs_2.md | 85 ++++++++++++++++++++++++++++++++++++++++++++ src/prelude.rs | 1 - 9 files changed, 141 insertions(+), 8 deletions(-) create mode 100644 guide/book.toml create mode 100644 guide/src/SUMMARY.md create mode 100644 guide/src/qs_1.md create mode 100644 guide/src/qs_2.md diff --git a/.gitignore b/.gitignore index 2c1955fc..42d0755d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ -target/ Cargo.lock +target/ +guide/build/ /gh-pages -__pycache__ *.so *.out @@ -9,7 +9,6 @@ __pycache__ *.pid *.sock *~ -*.egg-info/ # These are backup files generated by rustfmt **/*.rs.bk diff --git a/.travis.yml b/.travis.yml index 121ba990..922665bb 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,6 +29,13 @@ before_script: script: - USE_SKEPTIC=1 cargo test --features=alpn + + # Build without unstable flag + - cargo build + + # Test examples in guide. + - rustdoc --test guide/src/qs_2.md -L target/debug -L target/debug/deps + - | if [[ "$TRAVIS_RUST_VERSION" == "nightly" && $CLIPPY ]]; then cargo clippy @@ -40,6 +47,8 @@ after_success: if [[ "$TRAVIS_OS_NAME" == "linux" && "$TRAVIS_PULL_REQUEST" = "false" && "$TRAVIS_BRANCH" == "master" && "$TRAVIS_RUST_VERSION" == "nightly" ]]; then cargo doc --features alpn --no-deps && echo "" > target/doc/index.html && + cargo install mdbook && + cd guide && mdbook build -d ../target/doc/guide && cd .. && git clone https://github.com/davisp/ghp-import.git && ./ghp-import/ghp_import.py -n -p -f -m "Documentation upload" -r https://"$GH_TOKEN"@github.com/"$TRAVIS_REPO_SLUG.git" target/doc && echo "Uploaded documentation" diff --git a/build.rs b/build.rs index 3afd1029..1da14f1e 100644 --- a/build.rs +++ b/build.rs @@ -8,7 +8,7 @@ use std::{env, fs}; fn main() { if env::var("USE_SKEPTIC").is_ok() { // generates doc tests for `README.md`. - skeptic::generate_doc_tests(&["README.md"]); + skeptic::generate_doc_tests(&["README.md", "guide/src/qs_2.md"]); } else { let f = env::var("OUT_DIR").unwrap() + "/skeptic-tests.rs"; let _ = fs::File::create(f); diff --git a/examples/basic.rs b/examples/basic.rs index 011a6a8d..ff8cf744 100644 --- a/examples/basic.rs +++ b/examples/basic.rs @@ -11,7 +11,7 @@ use actix_web::error::{Error, Result}; use actix_web::middlewares::RequestSession; use futures::stream::{once, Once}; -/// somple handle +/// simple handler fn index(mut req: HttpRequest) -> Result { println!("{:?}", req); if let Ok(ch) = req.payload_mut().readany() { @@ -31,7 +31,7 @@ fn index(mut req: HttpRequest) -> Result { Ok(httpcodes::HTTPOk.into()) } -/// somple handle +/// async handler fn index_async(req: HttpRequest) -> Once { println!("{:?}", req); @@ -43,7 +43,7 @@ fn index_async(req: HttpRequest) -> Once .into())) } -/// handle with path parameters like `/user/{name}/` +/// handler with path parameters like `/user/{name}/` fn with_param(req: HttpRequest) -> Result { println!("{:?}", req); diff --git a/guide/book.toml b/guide/book.toml new file mode 100644 index 00000000..185156e2 --- /dev/null +++ b/guide/book.toml @@ -0,0 +1,3 @@ +title = "Actix web" +description = "Actix web framework guide" +author = "Actix Project and Contributors" diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md new file mode 100644 index 00000000..97c88675 --- /dev/null +++ b/guide/src/SUMMARY.md @@ -0,0 +1,4 @@ +# Summary + +[Quickstart](./qs_1.md) +- [Getting Started](./qs_2.md) diff --git a/guide/src/qs_1.md b/guide/src/qs_1.md new file mode 100644 index 00000000..09e83b58 --- /dev/null +++ b/guide/src/qs_1.md @@ -0,0 +1,34 @@ +# Quickstart + +Before you can start writing a actix web application, you’ll need a version of Rust installed. +We recommend you use rustup to install or configure such a version. + +## Install Rust + +Before we begin, we need to install Rust using the [rustup](https://www.rustup.rs/) installer: + +```bash +curl https://sh.rustup.rs -sSf | sh +``` + +If you already have rustup installed, run this command to ensure you have the latest version of Rust: + +```bash +rustup update +``` + +Actix web framework requies rust version 1.20 and up. + +## Running Examples + +The fastest way to start experimenting with actix web is to clone the actix web repository +and run the included examples in the examples/ directory. The following set of +commands runs the `basic` example: + +```bash +git clone https://github.com/actix/actix-web +cd actix-web +cargo run --example basic +``` + +Check `examples/` directory for more examples. diff --git a/guide/src/qs_2.md b/guide/src/qs_2.md new file mode 100644 index 00000000..823f5694 --- /dev/null +++ b/guide/src/qs_2.md @@ -0,0 +1,85 @@ +# Getting Started + +Let’s create and run our first actix web application. We’ll create a new Cargo project +that depends on actix web and then run the application. + +In previous section we already installed required rust version. Now let's create new cargo projects. + +## Hello, world! + +Let’s write our first actix web application! Start by creating a new binary-based +Cargo project and changing into the new directory: + +```bash +cargo new hello-world --bin +cd hello-world +``` + +Now, add actix and actix web as dependencies of your project by ensuring your Cargo.toml +contains the following: + +```toml +[dependencies] +actix = "0.3" +actix-web = { git = "https://github.com/actix/actix-web" } +``` + +In order to implement a web server, first we need to create a request handler. + +A request handler is a function that accepts a `HttpRequest` instance as its only parameter +and returns a `HttpResponse` instance or actor that uses `HttpContext` as an actor's context:: + +```rust,ignore +extern crate actix_web; +use actix_web::prelude::*; + +fn index(req: HttpRequest) -> Result { + Ok(httpcodes::HTTPOk.with_body("Hello world!")) +} +``` + +Next, create an `Application` instance and register the +request handler with the application's `resource` on a particular *HTTP method* and *path*:: + +```rust,ignore + let app = Application::default("/") + .resource("/", |r| r.handler(Method::GET, index) + .finish() +``` + +After that, application instance can be used with `HttpServer` to listen for incoming +connections: + +```rust,ignore + HttpServer::new(app).serve::<_, ()>("127.0.0.1:8088"); +``` + +That's it. Now, compile and run the program with cargo run. +Head over to ``http://localhost:8088/`` to see the results. + +Here is full source of main.rs file: + +```rust +extern crate actix; +extern crate actix_web; +use actix_web::prelude::*; + +fn index(req: HttpRequest) -> Result { + Ok(httpcodes::HTTPOk.with_body("Hello world!")) +} + +fn main() { + let sys = actix::System::new("example"); + + HttpServer::new( + Application::default("/") + .resource("/", |r| r.handler(Method::GET, index))) + .serve::<_, ()>("127.0.0.1:8088").unwrap(); + + println!("Started http server: 127.0.0.1:8088"); + // do not copy this line + actix::Arbiter::system().send(actix::msgs::SystemExit(0)); + + let _ = sys.run(); +} +``` diff --git a/src/prelude.rs b/src/prelude.rs index 6f7a777a..01c2a90e 100644 --- a/src/prelude.rs +++ b/src/prelude.rs @@ -1,7 +1,6 @@ //! The `actix-web` prelude pub use super::*; - pub use error::*; pub use application::ApplicationBuilder; pub use httpresponse::HttpResponseBuilder;