Faraday website edits (#987)

docs/_config.yml

@@ -8,7 +8,7 @@ theme_settings:
   # email: your-email@example.com
   description: >-
     Simple, but flexible HTTP client library, with support for multiple backends
-  footer_text: Copyright (c) 2009-2019 Rick Olson, Zack Hobson.
+  footer_text: "© 2009-2019 Rick Olson, Zack Hobson."
 
   # Icons
   github: 'lostisland/faraday'

docs/adapters/net_http.md

@@ -5,7 +5,7 @@ permalink: /adapters/net-http
 hide: true
 ---
 
-This Adapter uses the Net::HTTP client from the ruby standard library to make
+This Adapter uses the [`Net::HTTP`][rdoc] client from the Ruby standard library to make
 HTTP requests.
 
 ```ruby

docs/index.md

@@ -54,7 +54,6 @@ Table of contents:
   * [Writing Middleware][custom]
 * [Adapters][adapters]
 * [Testing][testing]
-
 * [Faraday API RubyDoc](http://www.rubydoc.info/gems/faraday)
 
 [github]:                   https://github.com/lostisland/faraday

docs/introduction/basics.md

@@ -5,13 +5,13 @@ permalink: /introduction/basics
 hide: true
 ---
 
-A simple `get` request can be performed simply calling the `get` class method:
+A `GET` request can be performed by calling the `.get` class method:
 
 ```ruby
 response = Faraday.get 'http://sushi.com/nigiri/sake.json'
 ```
 
-This works if you don't need to set up anything; you can roll with just the default middleware
+This works if you don't need to set up anything; you can roll with the default middleware
 stack and default adapter (see [Faraday::RackBuilder#initialize][rack_builder]).
 
 ## The Connection Object
@@ -22,15 +22,18 @@ A more flexible way to use Faraday is to start with a Connection object. If you
 conn = Faraday.new(url: 'http://www.sushi.com')
 ```
 
-Connections can also take an options hash as a parameter or be configured by using a block.
+Connections can also take an options hash as a parameter, or be configured with a block.
-Checkout the [Middleware][middleware] page for more details about how to use this block for configurations.
+Check out the [Middleware][middleware] page for more details about how to use this block for configurations.
-Since the default middleware stack uses `url_encoded` middleware and default adapter, use them on building your own middleware stack.
+Since the default middleware stack uses the `url_encoded` middleware and default adapter, use them on building your own middleware stack.
 
 ```ruby
 conn = Faraday.new(url: 'http://sushi.com') do |faraday|
-  faraday.request :url_encoded             # form-encode POST params
+  # form-encode POST params
-  faraday.response :logger                 # log requests and responses to $stdout
+  faraday.request :url_encoded
-  faraday.adapter Faraday.default_adapter  # make requests with Net::HTTP
+  # log requests and responses to $stdout
+  faraday.response :logger
+  # make requests with Net::HTTP
+  faraday.adapter Faraday.default_adapter
 end
 ```
 
@@ -40,33 +43,42 @@ Once you have the connection object, use it to make HTTP requests. You can pass
 conn = Faraday.new(url: 'http://sushi.com/nigiri')
 
 ## GET ##
-response = conn.get 'sake.json'             # GET http://sushi.com/nigiri/sake.json
 
-# You can override the path from the connection initializer by using an absolute path
+response = conn.get 'sake.json'
-response = conn.get '/maki/platters.json'   # GET http://sushi.com/maki/platters.json
+# => GET http://sushi.com/nigiri/sake.json
+
+# Using an absolute path overrides the path from the connection initializer
+response = conn.get '/maki/platters.json'
+# => GET http://sushi.com/maki/platters.json
  
 # You can then access the response body
 response.body
 
 # Path can also be empty. Parameters can be provided as a hash.
-conn.get '', { name: 'Maguro' }             # GET http://sushi.com/nigiri?name=Maguro
+conn.get '', { name: 'Maguro' }
+# => GET http://sushi.com/nigiri?name=Maguro
 
-conn.get do |req|                           # GET http://sushi.com/search?limit=100&page=2
+conn.get do |req|
   req.url '/search', page: 2
   req.params['limit'] = 100
 end
+# => GET http://sushi.com/search?limit=100&page=2
 
 ## POST ##
 
-# In case of a POST request, parameters are automatically put in the body as ww-form-urlencoded. 
+# Parameters for POST requests are automatically put in the body as
-conn.post '', { name: 'Maguro' }            # POST "name=maguro" to http://sushi.com/nigiri
+# www-form-urlencoded.
+conn.post '', { name: 'Maguro' }
+# => POST "name=maguro" to http://sushi.com/nigiri
 
-# post payload as JSON instead of www-form-urlencoded encoding
+# To post as JSON instead of www-form-urlencoded, set the request header
-conn.post do |req|                          # POST "{ "name": "Unagi" }" to http://sushi.com/nigiri
+conn.post do |req|
   req.url ''
   req.headers['Content-Type'] = 'application/json'
   req.body = '{ "name": "Unagi" }'
 end
+# => POST "{ "name": "Unagi" }" to http://sushi.com/nigiri
+
 ```
 
 [rack_builder]:   https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb

docs/introduction/customize.md

@@ -5,7 +5,7 @@ permalink: /introduction/customize
 hide: true
 ---
 
-Configuration can be setup with the connection and/or adjusted per request: 
+Configuration can be set up with the connection and/or adjusted per request: 
 
 ```ruby
 ## Connection options ##
@@ -26,8 +26,8 @@ This will be available in the `env` on all middleware.
 conn.get do |req|
   req.url '/search'
   req.options.context = {
-      foo: 'foo',
+    foo: 'foo',
-      bar: 'bar'
+    bar: 'bar'
   }
 end
 ```
@@ -39,31 +39,36 @@ This requires manually setting the parameter encoder and can be done on
 either per-connection or per-request basis.
 
 ```ruby
-# per-connection setting
+# Per-connection setting
 conn = Faraday.new request: { params_encoder: Faraday::FlatParamsEncoder }
 conn.get('', { roll: ['california', 'philadelphia'] })
 
-# per-request setting
+# Per-request setting
 conn.get do |req|
   req.options.params_encoder = Faraday::FlatParamsEncoder
   req.params = { roll: ['california', 'philadelphia'] }
 end
 ```
 
+### Custom serializers
+
+You can build your custom encoder, if you like.
+
 The value of Faraday `params_encoder` can be any object that responds to:
 
-* `encode(hash) #=> String`
+* `#encode(hash) #=> String`
-* `decode(string) #=> Hash`
+* `#decode(string) #=> Hash`
 
-so you can build your custom encoder, if you like.
+The encoder will affect both how Faraday processes query strings and how it
-The encoder will affect both how query strings are processed and how POST bodies
+serializes POST bodies.
-get serialized. The default encoder is Faraday::NestedParamsEncoder.
+
+The default encoder is `Faraday::NestedParamsEncoder`.
 
 ## Proxy
 
-Faraday will try to automatically infer the proxy settings from your system using `URI#find_proxy`.
+Faraday will try to automatically infer the proxy settings from your system using [`URI#find_proxy`][ruby-find-proxy].
 This will retrieve them from environment variables such as http_proxy, ftp_proxy, no_proxy, etc.
-If for any reason you want to disable this behaviour, you can do so by setting the global varibale `ignore_env_proxy`:
+If for any reason you want to disable this behaviour, you can do so by setting the global variable `ignore_env_proxy`:
 
 ```ruby
 Faraday.ignore_env_proxy = true
@@ -73,4 +78,6 @@ You can also specify a custom proxy when initializing the connection:
 
 ```ruby
 conn = Faraday.new('http://www.example.com', proxy: 'http://proxy.com')
-```
+```
+
+[ruby-find-proxy]: https://ruby-doc.org/stdlib-2.6.3/libdoc/uri/rdoc/URI/Generic.html#method-i-find_proxy

docs/introduction/streaming.md

@@ -6,12 +6,16 @@ hide: true
 ---
 
 Sometimes you might need to receive a streaming response.
-You can easily do this with the `on_data` request option:
+You can do this with the `on_data` request option.
+
+The `on_data` callback is a receives tuples of chunk Strings, and the total
+of received bytes so far.
+
+This example implements such a callback:
 
 ```ruby
-## Streaming responses ##
+# A buffer to store the streamed data
-
+streamed = []
-streamed = []                       # A buffer to store the streamed data
 
 conn.get('/nigiri/sake.json') do |req|
   # Set a callback which will receive tuples of chunk Strings
@@ -22,8 +26,9 @@ conn.get('/nigiri/sake.json') do |req|
   end
 end
 
-streamed.join                       # Joins all response chunks together 
+# Joins all response chunks together 
+streamed.join
 ```
 
-At the moment, this is only supported by the `Net::HTTP` adapter, but support for other adapters
+The `on_data` streaming is currently only supported by the `Net::HTTP` adapter. Other adapters
-will be provided in future.
+will be support this in the future.

docs/testing.md

@@ -19,11 +19,9 @@ conn = Faraday.new do |builder|
   builder.adapter :test do |stub|
     stub.get('/ebi') do |env|
       [
-        200, # status code
+        200,
-        {
+        { 'Content-Type': 'text/plain', },
-          'Content-Type': 'text/plain',
+        'shrimp'
-        }, # headers
-        'shrimp' # response body
       ]
     end
   end