From 056803d534234b15698a5a34280d340f9446bfe9 Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Sun, 5 Jul 2020 01:16:53 +0100
Subject: [PATCH] revamp readme and root doc page (#1590)
---
README.md | 90 ++++++++++++++++++++++++++++--------------------------
src/lib.rs | 90 +++++++++++++++++++++++++-----------------------------
2 files changed, 87 insertions(+), 93 deletions(-)
diff --git a/README.md b/README.md
index a9b5e011..4d6bac29 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,58 @@
<div align="center">
- <p><h1>Actix web</h1> </p>
- <p><strong>Actix web is a small, pragmatic, and extremely fast rust web framework</strong> </p>
+ <h1>Actix web</h1>
+ <p>
+ <strong>Actix web is a powerful, pragmatic, and extremely fast web framework for Rust</strong>
+ </p>
<p>
-[](https://travis-ci.org/actix/actix-web)
-[](https://codecov.io/gh/actix/actix-web)
[](https://crates.io/crates/actix-web)
-[](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://docs.rs/actix-web)
-[](https://crates.io/crates/actix-web)
[](https://blog.rust-lang.org/2020/02/27/Rust-1.41.1.html)
+<br />
+[](https://travis-ci.org/actix/actix-web)
+[](https://codecov.io/gh/actix/actix-web)
+[](https://crates.io/crates/actix-web)
+[](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
</p>
-
- <h3>
- <a href="https://actix.rs">Website</a>
- <span> | </span>
- <a href="https://gitter.im/actix/actix">Chat</a>
- <span> | </span>
- <a href="https://github.com/actix/examples">Examples</a>
- </h3>
</div>
-<br>
-Actix web is a simple, pragmatic and extremely fast web framework for Rust.
+## Features
-* Supported *HTTP/1.x* and *HTTP/2.0* protocols
+* Supports *HTTP/1.x* and *HTTP/2*
* Streaming and pipelining
* Keep-alive and slow requests handling
* Client/server [WebSockets](https://actix.rs/docs/websockets/) support
* Transparent content compression/decompression (br, gzip, deflate)
-* Configurable [request routing](https://actix.rs/docs/url-dispatch/)
+* Powerful [request routing](https://actix.rs/docs/url-dispatch/)
* Multipart streams
* Static assets
-* SSL support with OpenSSL or Rustls
+* SSL support using OpenSSL or Rustls
* Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
-* Includes an asynchronous [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
+* Includes an async [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
* Supports [Actix actor framework](https://github.com/actix/actix)
-* Supports Rust 1.40+
+* Runs on stable Rust 1.41+
-## Docs
+## Documentation
-* [API documentation (master)](https://actix.rs/actix-web/actix_web)
-* [API documentation (docs.rs)](https://docs.rs/actix-web)
-* [User guide](https://actix.rs)
+* [Website & User Guide](https://actix.rs)
+* [Examples Repository](https://actix.rs/actix-web/actix_web)
+* [API Documentation](https://docs.rs/actix-web)
+* [API Documentation (master branch)](https://actix.rs/actix-web/actix_web)
## Example
+<h2>
+ WARNING: This example is for the master branch which is currently in beta stages for v3. For
+ Actix web v2 see the <a href="https://actix.rs/docs/getting-started/">getting started guide</a>.
+</h2>
+
Dependencies:
```toml
[dependencies]
-actix-web = "2"
+actix-web = "3"
```
Code:
@@ -76,37 +76,39 @@ async fn main() -> std::io::Result<()> {
### More examples
-* [Basics](https://github.com/actix/examples/tree/master/basics/)
-* [Stateful](https://github.com/actix/examples/tree/master/state/)
-* [Multipart streams](https://github.com/actix/examples/tree/master/multipart/)
-* [Simple websocket](https://github.com/actix/examples/tree/master/websocket/)
-* [Tera](https://github.com/actix/examples/tree/master/template_tera/)
-* [Askama](https://github.com/actix/examples/tree/master/template_askama/) templates
-* [Diesel integration](https://github.com/actix/examples/tree/master/diesel/)
-* [r2d2](https://github.com/actix/examples/tree/master/r2d2/)
-* [OpenSSL](https://github.com/actix/examples/tree/master/openssl/)
-* [Rustls](https://github.com/actix/examples/tree/master/rustls/)
-* [Tcp/Websocket chat](https://github.com/actix/examples/tree/master/websocket-chat/)
-* [Json](https://github.com/actix/examples/tree/master/json/)
+* [Basic Setup](https://github.com/actix/examples/tree/master/basics/)
+* [Application State](https://github.com/actix/examples/tree/master/state/)
+* [JSON Handling](https://github.com/actix/examples/tree/master/json/)
+* [Multipart Streams](https://github.com/actix/examples/tree/master/multipart/)
+* [Diesel Integration](https://github.com/actix/examples/tree/master/diesel/)
+* [r2d2 Integration](https://github.com/actix/examples/tree/master/r2d2/)
+* [Simple WebSocket](https://github.com/actix/examples/tree/master/websocket/)
+* [Tera Templates](https://github.com/actix/examples/tree/master/template_tera/)
+* [Askama Templates](https://github.com/actix/examples/tree/master/template_askama/)
+* [HTTPS using Rustls](https://github.com/actix/examples/tree/master/rustls/)
+* [HTTPS using OpenSSL](https://github.com/actix/examples/tree/master/openssl/)
+* [WebSocket Chat](https://github.com/actix/examples/tree/master/websocket-chat/)
You may consider checking out
[this directory](https://github.com/actix/examples/tree/master/) for more examples.
## Benchmarks
-* [TechEmpower Framework Benchmark](https://www.techempower.com/benchmarks/#section=data-r19)
+One of the fastest web frameworks available according to the
+[TechEmpower Framework Benchmark](https://www.techempower.com/benchmarks/#section=data-r19).
## License
This project is licensed under either of
-* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
-* MIT license ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
+* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+ [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
+* MIT license ([LICENSE-MIT](LICENSE-MIT) or
+ [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
at your option.
## Code of Conduct
-Contribution to the actix-web crate is organized under the terms of the
-Contributor Covenant, the maintainer of actix-web, @fafhrd91, promises to
-intervene to uphold that code of conduct.
+Contribution to the actix-web crate is organized under the terms of the Contributor Covenant, the
+maintainers of Actix web, promises to intervene to uphold that code of conduct.
diff --git a/src/lib.rs b/src/lib.rs
index 844f952c..eb46af66 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,79 +1,72 @@
#![warn(rust_2018_idioms, warnings)]
#![allow(clippy::needless_doctest_main, clippy::type_complexity)]
-//! Actix web is a small, pragmatic, and extremely fast web framework
-//! for Rust.
+//! Actix web is a powerful, pragmatic, and extremely fast web framework for Rust.
//!
//! ## Example
//!
//! ```rust,no_run
-//! use actix_web::{web, App, Responder, HttpServer};
+//! use actix_web::{get, web, App, HttpServer, Responder};
//!
-//! async fn index(info: web::Path<(String, u32)>) -> impl Responder {
-//! format!("Hello {}! id:{}", info.0, info.1)
+//! #[get("/{id}/{name}/index.html")]
+//! async fn index(info: web::Path<(u32, String)>) -> impl Responder {
+//! format!("Hello {}! id:{}", info.1, info.0)
//! }
//!
//! #[actix_web::main]
//! async fn main() -> std::io::Result<()> {
-//! HttpServer::new(|| App::new().service(
-//! web::resource("/{name}/{id}/index.html").to(index))
-//! )
+//! HttpServer::new(|| App::new().service(index))
//! .bind("127.0.0.1:8080")?
//! .run()
//! .await
//! }
//! ```
//!
-//! ## Documentation & community resources
+//! ## Documentation & Community Resources
//!
-//! Besides the API documentation (which you are currently looking
-//! at!), several other resources are available:
+//! In addition to this API documentation, several other resources are available:
//!
-//! * [User Guide](https://actix.rs/docs/)
-//! * [Chat on gitter](https://gitter.im/actix/actix)
-//! * [GitHub repository](https://github.com/actix/actix-web)
-//! * [Cargo package](https://crates.io/crates/actix-web)
+//! * [Website & User Guide](https://actix.rs/)
+//! * [Examples Repository](https://github.com/actix/examples)
+//! * [Community Chat on Gitter](https://gitter.im/actix/actix-web)
//!
-//! To get started navigating the API documentation you may want to
-//! consider looking at the following pages:
+//! To get started navigating the API docs, you may consider looking at the following pages first:
//!
-//! * [App](struct.App.html): This struct represents an actix-web
-//! application and is used to configure routes and other common
-//! settings.
+//! * [App](struct.App.html): This struct represents an Actix web application and is used to
+//! configure routes and other common application settings.
//!
-//! * [HttpServer](struct.HttpServer.html): This struct
-//! represents an HTTP server instance and is used to instantiate and
-//! configure servers.
+//! * [HttpServer](struct.HttpServer.html): This struct represents an HTTP server instance and is
+//! used to instantiate and configure servers.
//!
-//! * [web](web/index.html): This module
-//! provides essential helper functions and types for application registration.
+//! * [web](web/index.html): This module provides essential types for route registration as well as
+//! common utilities for request handlers.
//!
-//! * [HttpRequest](struct.HttpRequest.html) and
-//! [HttpResponse](struct.HttpResponse.html): These structs
-//! represent HTTP requests and responses and expose various methods
-//! for inspecting, creating and otherwise utilizing them.
+//! * [HttpRequest](struct.HttpRequest.html) and [HttpResponse](struct.HttpResponse.html): These
+//! structs represent HTTP requests and responses and expose methods for creating, inspecting,
+//! and otherwise utilizing them.
//!
//! ## Features
//!
-//! * Supported *HTTP/1.x* and *HTTP/2.0* protocols
+//! * Supports *HTTP/1.x* and *HTTP/2*
//! * Streaming and pipelining
//! * Keep-alive and slow requests handling
-//! * `WebSockets` server/client
+//! * Client/server [WebSockets](https://actix.rs/docs/websockets/) support
//! * Transparent content compression/decompression (br, gzip, deflate)
-//! * Configurable request routing
+//! * Powerful [request routing](https://actix.rs/docs/url-dispatch/)
//! * Multipart streams
-//! * SSL support with OpenSSL or `native-tls`
-//! * Middlewares (`Logger`, `Session`, `CORS`, `DefaultHeaders`)
+//! * Static assets
+//! * SSL support using OpenSSL or Rustls
+//! * Middlewares ([Logger, Session, CORS, etc](https://actix.rs/docs/middleware/))
+//! * Includes an async [HTTP client](https://actix.rs/actix-web/actix_web/client/index.html)
//! * Supports [Actix actor framework](https://github.com/actix/actix)
-//! * Supported Rust version: 1.40 or later
+//! * Runs on stable Rust 1.41+
//!
-//! ## Package feature
+//! ## Crate Features
//!
-//! * `client` - enables http client (default enabled)
-//! * `compress` - enables content encoding compression support (default enabled)
-//! * `openssl` - enables ssl support via `openssl` crate, supports `http/2`
-//! * `rustls` - enables ssl support via `rustls` crate, supports `http/2`
-//! * `secure-cookies` - enables secure cookies support
+//! * `compress` - content encoding compression support (enabled by default)
+//! * `openssl` - HTTPS support via `openssl` crate, supports `HTTP/2`
+//! * `rustls` - HTTPS support via `rustls` crate, supports `HTTP/2`
+//! * `secure-cookies` - secure cookies support
mod app;
mod app_service;
@@ -97,12 +90,10 @@ pub mod test;
mod types;
pub mod web;
-pub use actix_web_codegen::*;
-pub use actix_rt as rt;
-
-// re-export for convenience
pub use actix_http::Response as HttpResponse;
pub use actix_http::{body, cookie, http, Error, HttpMessage, ResponseError, Result};
+pub use actix_rt as rt;
+pub use actix_web_codegen::*;
pub use crate::app::App;
pub use crate::extract::FromRequest;
@@ -203,19 +194,20 @@ pub mod dev {
}
pub mod client {
- //! An HTTP Client
+ //! Actix web async HTTP client.
//!
//! ```rust
//! use actix_web::client::Client;
//!
- //! #[actix_rt::main]
+ //! #[actix_web::main]
//! async fn main() {
//! let mut client = Client::default();
//!
//! // Create request builder and send request
//! let response = client.get("http://www.rust-lang.org")
- //! .header("User-Agent", "Actix-web")
- //! .send().await; // <- Send http request
+ //! .header("User-Agent", "actix-web/3.0")
+ //! .send() // <- Send request
+ //! .await; // <- Wait for response
//!
//! println!("Response: {:?}", response);
//! }