Fix documentation for v0.6.0

README.rst

@@ -86,9 +86,9 @@ Uplink officially supports Python 2.7 & 3.3-3.7.
 .. |marshmallow| replace:: ``marshmallow``
 .. |requests-oauthlib| replace:: ``requests-oauthlib``
 .. _`Non-blocking I/O support`: https://github.com/prkumar/uplink/tree/master/examples/async-requests
-.. _`Supply your own session`: https://uplink.readthedocs.io/en/latest/user/clients.html#swapping-out-the-default-http-client
+.. _`Supply your own session`: https://uplink.readthedocs.io/en/latest/user/clients.html#swapping-out-the-default-http-session
 .. _`marshmallow`: https://github.com/prkumar/uplink/tree/master/examples/marshmallow
-.. _`custom converters`: https://uplink.readthedocs.io/en/latest/user/serialization.html#custom-serialization
+.. _`custom converters`: https://uplink.readthedocs.io/en/latest/user/serialization.html#custom-json-deserialization
 .. _`handling collections`: https://uplink.readthedocs.io/en/latest/user/serialization.html#converting-collections
 .. _`custom response and error handling`: https://uplink.readthedocs.io/en/latest/user/quickstart.html#response-and-error-handling
 .. _`protobuf support`: https://github.com/prkumar/uplink-protobuf

docs/source/user/clients.rst

@@ -1,14 +1,27 @@
 Clients
 *******
 
+To use a common English metaphor: Uplink stands on the shoulders of giants.
+
+Uplink doesn't implement any code to handle HTTP protocol stuff
+directly; for that, the library delegates to an actual HTTP client, such
+as Requests or Aiohttp. Whatever backing client you choose, when a
+request method on a :class:`Consumer` subclass is invoked, Uplink
+ultimately interacts with the backing library's interface, at minimum to
+submit requests and read responses.
+
+This section covers the interaction between Uplink and the backing HTTP
+client library of your choosing, including how to specify your
+selection.
+
 .. _swap_default_http_client:
 
-Swapping Out the Default HTTP Client
-====================================
+Swapping Out the Default HTTP Session
+=====================================
 
 By default, Uplink sends requests using the Requests library. You can
-configure the backing HTTP client using the :obj:`client` parameter of the
-:py:class:`~uplink.Consumer` constructor:
+configure the backing HTTP client object using the :obj:`client`
+parameter of the :py:class:`~uplink.Consumer` constructor:
 
 .. code-block:: python
 
@@ -25,6 +38,26 @@ object:
     session.verify = False
     github = GitHub(BASE_URL, client=session)
 
+This also go for session objects from other HTTP client libraries that
+Uplink supports, such as :mod:`aiohttp` (i.e., a custom
+:class:`~aiohttp.ClientSession` works here, as well).
+
+Following the above example, the :obj:`client` parameter also accepts an
+instance of any :class:`requests.Session` subclass. This makes it easy
+to leverage functionality from third-party Requests extensions, such as
+`requests-oauthlib`_, with minimal integration overhead:
+
+.. code-block:: python
+
+    from requests_oauthlib import OAuth2Session
+
+    session = OAuth2Session(...)
+    api = MyApi(BASE_URL, client=session)
+
+
+.. |requests-oauthlib| replace:: ``requests-oauthlib``
+.. _`requests-oauthlib`: https://github.com/requests/requests-oauthlib
+
 .. _sync_vs_async:
 
 Synchronous vs. Asynchronous

docs/source/user/serialization.rst

@@ -151,16 +151,16 @@ Converting Collections
 ======================
 
 Data-driven web applications, such as social networks and forums, devise
-a lot of functionality around large queries on related data. And, these
-APIs normally encode the results of these queries as collections of a
-common **type**. Examples include a curated feed of **posts** from
-subscribed accounts, the top **restaurants** in your area, upcoming
-**tasks** on a checklist, etc.
+a lot of functionality around large queries on related data. Their APIs
+normally encode the results of these queries as collections of a common
+**type**. Examples include a curated feed of **posts** from subscribed
+accounts, the top **restaurants** in your area, upcoming *tasks** on a
+checklist, etc.
 
 You can use the other strategies in this section to add serialization
 support for a specific type, such as a **post** or a **restaurant**.
-Importantly, once added, this support automatically extends to
-collections of that type, such as sequences and mappings.
+Once added, this support automatically extends to collections of that
+type, such as sequences and mappings.
 
 For example, consider a hypothetical Task Management API that supports
 adding tasks to one or more user-created checklists. Here's the JSON
@@ -195,11 +195,11 @@ register a custom converter with :meth:`loads.from_json
 :ref:`custom_json_deserialization`. For the sake of brevity, I'll omit the
 implementation here, but you can follow the link above for details.
 
-Now, Uplink lets us leverage the added support to handle collections of
-type :class:`Task`. The :mod:`uplink.types` module exposes two
-collection types, :data:`~uplink.List` and :data:`~uplink.types.Dict`,
-to be used as function return type annotations. In our example, the
-query for pending tasks returns a list:
+Notably, Uplink lets us leverage the added support to also handle
+collections of type :class:`Task`. The :mod:`uplink.types` module
+exposes two collection types, :data:`~uplink.List` and
+:data:`~uplink.types.Dict`, to be used as function return type
+annotations. In our example, the query for pending tasks returns a list:
 
 .. code-block:: python
    :emphasize-lines: 6
@@ -263,11 +263,11 @@ could look like:
       """Adapter for Python's Pickle protocol."""
 
       def create_response_body_converter(self, cls, request_definition):
-         # Return callable that deserialize response body into Python object.
+         # Return callable to deserialize response body into Python object.
          return lambda response: pickle.loads(response.content)
 
       def create_request_body_converter(self, cls, request_definition):
-         # Return callable that serialize Python object into bytes.
+         # Return callable to serialize Python object into bytes.
          return pickle.dumps
 
 Then, when instantiating a new consumer, you can supply this