Merges #970.

Adds table of content to homepage.
Adds details page for logger middleware.

README.md

@@ -33,7 +33,7 @@ Rack::Test, and a Test adapter for stubbing requests by hand.
 * [Faraday API RubyDoc](http://www.rubydoc.info/gems/faraday)
 * [Middleware](./docs/middleware)
   * [Middleware Environment](./docs/middleware/env.md)
-* [Testing](./docs/adapters/testing.md)
+* [Testing](docs/testing.md)
 
 ## Usage
 
@@ -61,33 +61,6 @@ conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
   faraday.response :logger                  # log requests and responses to $stdout
   faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
 end
-
-# Filter sensitive information from logs with a regex matcher
-
-conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday|
-  faraday.request  :url_encoded             # form-encode POST params
-  faraday.response :logger do | logger |
-    logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]')
-  end
-  faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
-end
-
-# Override the log formatting on demand
-
-class MyFormatter < Faraday::Response::Logger::Formatter
-  def request(env)
-    info('Request', env)
-  end
-
-  def request(env)
-    info('Response', env)
-  end
-end
-
-conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday|
-  faraday.response :logger, StructLogger.new(STDOUT), formatter: MyFormatter
-end
-
 ```
 
 Once you have the connection object, use it to make HTTP requests. You can pass parameters to it in a few different ways:

docs/_sass/faraday.sass

@@ -1,15 +1,30 @@
 // Custom Styles added on top of the theme.
 
 .btn
+  color: white
   background-color: $link-color
   padding: 5px 10px
   border-radius: 4px
   &:hover
     background-color: darken($link-color, 10%)
-
-p
-  a
     color: white
-    &:hover
-      color: white
-      text-decoration: none
+      text-decoration: none
+
+.text-center
+  text-align: center
+
+.mt-60
+  margin-top: 60px
+
+pre.highlight
+  padding: 20px
+  background-color: #F6F6F6
+  border-radius: 4px
+  code
+    word-wrap: normal
+    overflow: scroll
+
+code.highlighter-rouge
+  background-color: #EEE
+  padding: 0 5px
+  border-radius: 3px

docs/adapters/index.md

@@ -0,0 +1,43 @@
+---
+layout: page
+title: "Adapters"
+permalink: /adapters
+hide: true
+---
+
+Adapters are what performs the HTTP Request in the background.
+They receive a `Faraday::Request` and make the actual call, returning a `Faraday::Response`.
+Faraday allows you to change the adapter at any time through the configuration block.
+
+{: .mt-60}
+## Supported adapters
+
+Faraday supports these adapters out of the box:
+
+* [Net::HTTP][net_http] _(this is the default adapter)_
+* [Net::HTTP::Persistent][persistent]
+* [Excon][excon]
+* [Patron][patron]
+* [EM-Synchrony][em-synchrony]
+* [HTTPClient][httpclient]
+
+Adapters are slowly being moved into their own gems, or bundled with HTTP clients.
+Please refer to their documentation for usage examples.
+Here is the list of known external adapters:
+
+* [Typhoeus][typhoeus]
+* [HTTP.rb][faraday-http]
+
+Faraday also includes a Rack adapter for hitting loaded Rack applications through
+Rack::Test, and a [Test adapter][testing] for stubbing requests by hand.
+
+
+[net_http]:     ./net-http
+[persistent]:   ./net-http-persistent
+[excon]:        ./excon
+[patron]:       ./patron
+[em-synchrony]: ./em-synchrony
+[httpclient]:   ./httpclient
+[typhoeus]:     https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
+[faraday-http]: https://github.com/lostisland/faraday-http
+[testing]:      ../testing

docs/index.md

@@ -12,4 +12,41 @@ hide: true
 Faraday is an HTTP client library that provides a common interface over many adapters (such as Net::HTTP)
 and embraces the concept of Rack middleware when processing the request/response cycle.
 
-[Click me](http://www.google.com){: .btn}
+{: .text-center}
+[<i class="fab fa-fw fa-github"> </i> Fork on GitHub](https://github.com/lostisland/faraday){: .btn}
+[<i class="fab fa-fw fa-gitter"> </i> Chat with us](https://gitter.im/lostisland/faraday){: .btn}
+
+{: .mt-60}
+## Getting Started
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faraday'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install faraday
+```
+
+You can also install the [`faraday_middleware`](https://github.com/lostisland/faraday_middleware)
+extension gem to access a collection of useful Faraday middleware.
+
+{: .mt-60}
+## Usage
+
+Table of contents:
+
+* [Faraday API RubyDoc](http://www.rubydoc.info/gems/faraday)
+* [Adapters](./adapters)
+* [Middleware](./middleware)
+  * [Middleware Environment](./middleware/env)
+* [Testing](./testing)

docs/middleware/env.md

@@ -1,3 +1,8 @@
-# Faraday Env
+---
+layout: page
+title: "Faraday Env"
+permalink: /middleware/env
+hide: true
+---
 
 Faraday loves the environment.

docs/middleware/index.md

@@ -1,4 +1,9 @@
-# Middleware Usage
+---
+layout: page
+title: "Middleware Usage"
+permalink: /middleware
+hide: true
+---
 
 A `Faraday::Connection` uses a `Faraday::RackBuilder` to assemble a
 Rack-inspired middleware stack for making HTTP requests. Each middleware runs
@@ -7,6 +12,8 @@ run, Faraday will return a `Faraday::Response` to the end user.
 
 ## Middleware Types
 
+### Request
+
 **Request middleware** can modify Request details before the Adapter runs. Most
 middleware set Header values or transform the request body based on the
 content type.
@@ -17,8 +24,17 @@ base64 representation.
 multipart form request.
 * `UrlEncoded` converts a `Faraday::Request#body` hash of key/value pairs into a url-
 encoded request body.
-
-**Adapters** make requests. TBD
-
 * `Retry` automatically retries requests that fail due to intermittent client
 or server errors (such as network hiccups).
+
+
+### Response
+
+**Response middleware** receives the response from the adapter and can modify its details
+before returning it.
+
+* [`Logger`][logger] logs both the request and the response body and headers.
+* `RaiseError` checks the response HTTP code and raises an exception if not in the 2xx range.
+
+
+[logger]:               ./logger

docs/middleware/response/logger.md

@@ -0,0 +1,92 @@
+---
+layout: page
+title: "Logger Middleware"
+permalink: /middleware/logger
+hide: true
+---
+
+The `Logger` middleware logs both the request and the response body and headers.
+It is highly customizable and allows to mask confidential information if necessary.
+
+### Basic Usage
+
+```ruby
+conn = Faraday.new(url: 'http://sushi.com') do |faraday|
+  faraday.response :logger # log requests and responses to $stdout
+end
+
+conn.get
+# => INFO  -- request: GET http://sushi.com/
+# => DEBUG -- request: User-Agent: "Faraday v1.0.0"
+# => INFO  -- response: Status 301
+# => DEBUG -- response: date: "Sun, 19 May 2019 16:05:40 GMT"
+```
+
+### Customize the logger
+
+By default, the `Logger` middleware uses the Ruby `Logger.new($stdout)`.
+You can customize it to use any logger you want by providing it when you add the middleware to the stack:
+
+```ruby
+conn = Faraday.new(url: 'http://sushi.com') do |faraday|
+  faraday.response :logger, MyLogger.new($stdout)
+end
+```
+
+### Include and exclude headers/bodies
+
+By default, the `logger` middleware logs only headers for security reasons, however, you can configure it
+to log bodies as well, or disable headers logging if you need to. To do so, simply provide a configuration hash
+when you add the middleware to the stack:
+
+```ruby
+conn = Faraday.new(url: 'http://sushi.com') do |faraday|
+  faraday.response :logger, nil, { headers: true, bodies: true }
+end
+```
+
+Please note this only works with the default formatter.
+
+### Filter sensitive information
+
+You can filter sensitive information from Faraday logs using a regex matcher:
+
+```ruby
+conn = Faraday.new(url: 'http://sushi.com') do |faraday|
+  faraday.response :logger do | logger |
+    logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]')
+  end
+end
+
+conn.get('/', api_key: 'secret')
+# => INFO  -- request: GET http://sushi.com/?api_key=[REMOVED]
+# => DEBUG -- request: User-Agent: "Faraday v1.0.0"
+# => INFO  -- response: Status 301
+# => DEBUG -- response: date: "Sun, 19 May 2019 16:12:36 GMT"
+```
+
+### Customize the formatter
+
+You can also provide a custom formatter to control how requests and responses are logged.
+Any custom formatter MUST implement the `request` and `response` method, with one argument which
+will be passed being the Faraday environment. 
+If you make your formatter inheriting from `Faraday::Response::Logger::Formatter`,
+then the methods `debug`, `info`, `warn`, `error` and `fatal` are automatically delegated to the logger.
+
+```ruby
+class MyFormatter < Faraday::Logging::Formatter
+  def request(env)
+    # Build a custom message using `env`
+    info('Request') { 'Sending Request' }
+  end
+
+  def response(env)
+    # Build a custom message using `env` 
+    info('Response') { 'Response Received' }
+  end
+end
+
+conn = Faraday.new(url: 'http://sushi.com/api_key=s3cr3t') do |faraday|
+  faraday.response :logger, nil, formatter: MyFormatter
+end
+```

docs/testing.md

@@ -1,4 +1,9 @@
-# Testing
+---
+layout: page
+title: "Testing"
+permalink: /testing
+hide: true
+---
 
 The built-in Faraday Test adapter lets you define stubbed HTTP requests. This can
 be used to mock out network services in an application's unit tests.