Update README and documentation

Author: joowani

README.rst

@@ -43,17 +43,17 @@ Announcements
 Features
 ========
 
-- Clean Pythonic interface
-- Lightweight
-- High ArangoDB REST API coverage
+- Clean Pythonic interface.
+- Lightweight.
+- High ArangoDB REST API coverage.
 
 Compatibility
 =============
 
-- Python versions 2.7, 3.4, 3.5 and 3.6 are supported
-- Python-arango 4.x supports ArangoDB 3.3+ (recommended)
-- Python-arango 3.x supports ArangoDB 3.0 ~ 3.2 only
-- Python-arango 2.x supports ArangoDB 1.x ~ 2.x only
+- Python versions 2.7, 3.4, 3.5 and 3.6 are supported.
+- Python-arango 4.x supports ArangoDB 3.3+ (recommended).
+- Python-arango 3.x supports ArangoDB 3.0 ~ 3.2 only.
+- Python-arango 2.x supports ArangoDB 1.x ~ 2.x only.
 
 Installation
 ============

docs/contributing.rst

@@ -7,15 +7,15 @@ Requirements
 Before submitting a pull request on GitHub_, please make sure you meet the
 following **requirements**:
 
-* The pull request points to dev_ (development) branch.
+* The pull request points to the dev_ (development) branch.
 * All changes are squashed into a single commit (I like to use ``git rebase -i``
   to do this).
 * The commit message is in present tense (good: "Add feature", bad:
   "Added feature").
 * Correct and consistent style: Sphinx_-compatible docstrings, correct snake
   and camel casing, and PEP8_ compliance (see below).
 * No classes/methods/functions with missing docstrings or commented-out lines.
-  You can take a look at the existing code in python-arango for examples.
+  You can take a look at the source code on GitHub_ for examples.
 * The test coverage_ remains at %100. You may find yourself having to write
   superfluous unit tests to keep this number up. If a piece of code is trivial
   and has no need for tests, use this_ to exclude it from coverage.
@@ -24,11 +24,11 @@ following **requirements**:
 * Does not break backward-compatibility (unless there is a really good reason).
 * Compatibility with all supported Python versions: 2.7, 3.4, 3.5 and 3.6.
 
-.. note::
+.. warning::
     The dev branch is occasionally rebased_, and its commit history may be
     overwritten in the process. Before you begin feature work, git fetch or
     pull to ensure that your local branch has not diverged. If you see git
-    conflicts and want to start from scratch, run these commands:
+    conflicts and just want to start from scratch, run these commands:
 
     .. code-block:: bash
 
@@ -92,7 +92,7 @@ Documentation
 =============
 
 The documentation (including the README) is written in reStructuredText_ and
-uses Sphinx_. To build the HTML version of the documentation on your local
+uses Sphinx_. To build an HTML version of the documentation on your local
 machine:
 
 .. code-block:: bash

docs/errors.rst

@@ -9,8 +9,8 @@ Server Errors
 =============
 
 :class:`arango.exceptions.ArangoServerError` exceptions lightly wrap non-2xx
-HTTP responses coming from ArangoDB. Each exception contains the error message,
-error code and HTTP request response details.
+HTTP responses coming from ArangoDB. Each exception object contains the error
+message, error code and HTTP request response details.
 
 **Example:**
 

docs/http.rst

@@ -2,13 +2,13 @@ Using Custom HTTP Clients
 -------------------------
 
 Python-arango lets you use your own HTTP clients for sending API requests to
-ArangoDB server. The default implementation uses the Requests_ library.
+ArangoDB server. The default implementation uses the requests_ library.
 
 Your HTTP client must inherit :class:`arango.http.HTTPClient` and implement its
 abstract method :func:`arango.http.HTTPClient.send_request`. The method must
 return valid (fully populated) instances of :class:`arango.response.Response`.
 
-For example, let's say you want to use your own HTTP client with:
+For example, let's say your HTTP client needs:
 
 * Automatic retries
 * Additional HTTP header called ``x-my-header``
@@ -150,8 +150,8 @@ Then you would inject your client as follows:
         http_client=CustomHTTPClient()
     )
 
-For more information on how to use a ``requests.Session``, refer to
-`Requests documentation`_.
+For more information on how to configure a ``requests.Session`` object, refer
+to `requests documentation`_.
 
-.. _Requests: https://github.com/requests/requests
-.. _Requests documentation: http://docs.python-requests.org/en/master/user/advanced/#session-objects
+.. _requests: https://github.com/requests/requests
+.. _requests documentation: http://docs.python-requests.org/en/master/user/advanced/#session-objects

docs/overview.rst

@@ -3,7 +3,7 @@ Getting Started
 
 Examples often speak louder than words, so this documentation relies heavily
 on sample code snippets with comments. Here is the first example showing how
-**python-arango** client can be initialized and used:
+a **python-arango** client can be initialized and used:
 
 .. testcode::