some overview text for guide

build.rs

@@ -6,11 +6,16 @@ use std::{env, fs};
 
 #[cfg(unix)]
 fn main() {
+    let f = env::var("OUT_DIR").unwrap() + "/skeptic-tests.rs";
     if env::var("USE_SKEPTIC").is_ok() {
+        let _ = fs::remove_file(f);
         // generates doc tests for `README.md`.
-        skeptic::generate_doc_tests(&["README.md", "guide/src/qs_2.md"]);
+        skeptic::generate_doc_tests(
+            &["README.md",
+              "guide/src/qs_2.md",
+              "guide/src/qs_3.md",
+            ]);
     } else {
-        let f = env::var("OUT_DIR").unwrap() + "/skeptic-tests.rs";
         let _ = fs::File::create(f);
     }
 

guide/src/SUMMARY.md

@@ -2,3 +2,4 @@
 
 [Quickstart](./qs_1.md)
 - [Getting Started](./qs_2.md)
+- [Actix web overview](./qs_3.md)

guide/src/qs_3.md

@@ -0,0 +1,78 @@
+# Overview
+
+Actix web provides some primitives to build web servers and applications with Rust.
+It provides routing, middlewares, pre-processing of requests, and post-processing of responses,
+websocket protcol handling, multipart streams, etc.
+
+
+## Application
+
+All actix web server is built around `Application` instance.
+It is used for registering handlers for routes and resources, middlewares.
+Also it stores applicationspecific state that is shared accross all handlers 
+within same application.
+
+Application acts as namespace for all routes, i.e all routes for specific application
+has same url path prefix:
+
+```rust,ignore
+   let app = Application::default("/prefix")
+       .resource("/index.html", |r| r.handler(Method::GET, index)
+       .finish()
+```
+
+In this example application with `/prefix` prefix and `index.html` resource
+get created. This resource is available as on `/prefix/index.html` url.
+
+### Application state
+
+Application state is shared with all routes within same application.
+State could be accessed with `HttpRequest::state()` method. It is read-only
+but interior mutability pattern with `RefCell` could be used to archive state mutability.
+State could be accessed with `HttpRequest::state()` method or 
+`HttpContext::state()` in case of http actor.
+
+Let's write simple application that uses shared state. We are going to store requests count
+in the state: 
+ 
+```rust
+extern crate actix;
+extern crate actix_web;
+
+use std::cell::Cell;
+use actix_web::prelude::*;
+
+// This struct represents state
+struct AppState {
+    counter: Cell<usize>,
+}
+
+fn index(req: HttpRequest<AppState>) -> HttpResponse {
+    let count = req.state().counter.get() + 1; // <- get count
+    req.state().counter.set(count);            // <- store new count in state
+    httpcodes::HTTPOk.with_body(               // <- response with count
+        format!("Num of requests: {}", count))
+}
+
+fn main() {
+    let sys = actix::System::new("example");
+
+    HttpServer::new(
+        Application::build("/", AppState{counter: Cell::new(0)})
+            .resource("/", |r| r.handler(Method::GET, index)))
+        .serve::<_, ()>("127.0.0.1:8088").unwrap();
+
+    println!("Started http server: 127.0.0.1:8088");
+    actix::Arbiter::system().send(actix::msgs::SystemExit(0)); // <- remove this line, this code stops system during testing
+
+    let _ = sys.run();
+}
+```
+
+## Handler
+
+A request handler can have several different forms. Simple function
+that accepts `HttpRequest` and returns `HttpResponse` or any type that can be converted
+into `HttpResponse`. Function that that accepts `HttpRequest` and 
+returns `Stream<Item=Frame, Error=Error>`. Or http actor, i.e. actor that has `HttpContext<A>`
+as a context.