WIP

README.rst

@@ -3,9 +3,6 @@ python-:green:`arango`
 
 Python driver for ArangoDB_ HTTP REST API.
 
-
-
-
 .. _ArangoDB: https://www.arangodb.com
 
 Overview
@@ -16,9 +13,9 @@ Overview
     - ArangoDB version 3.x
     - Python versions 2.7.x, 3.4.x and 3.5.x.
 
-
-Annoucements
-============
+.. note::
+    Version 3.x of python-arango is **not** backwards compatible with
+    ArangoDB versions 2.8.x and under
 
 
 Installation

docs/admin.rst

@@ -59,4 +59,4 @@ For more information on the HTTP REST API visit this
     client.reload_routing()
 
 
-Refer to the :ref:`ArangoClient` class for more details on the methods above.
+Refer to :ref:`ArangoClient` for more details on the methods above.

docs/async.rst

@@ -45,5 +45,5 @@ visit this `page <https://docs.arangodb.com/HTTP/AsyncResultsManagement>`_.
     job4.clear()
 
 
-Refer to the :ref:`AsyncExecution` and :ref:`AsyncJob` classes for more details
-on the methods above.
+Refer to the :ref:`AsyncExecution` and :ref:`AsyncJob` classes for more
+details on the methods above.

docs/collection.rst

@@ -7,11 +7,9 @@ underscore characters.
 
 There are two types of collections: **document collections** which contain
 :doc:`documents <document>` (standard) or **edge collections** which contain
-:ref:`edges <edge-documents>`.
-
-Be default, collections use the **traditional** key generator, which generates
-key values in a non-deterministic fashion. A deterministic, auto-increment
-key generator can be used as well.
+:ref:`edges <edge-documents>`. By default, collections use the **traditional**
+key generator, which generates key values in a non-deterministic fashion. A
+deterministic, auto-increment key generator can be used as well.
 
 For more information on the HTTP REST API for collection management visit this
 `page <https://docs.arangodb.com/HTTP/Collection>`__.

docs/cursor.rst

@@ -2,12 +2,11 @@ Cursors
 -------
 
 Many operations defined in python-arango (including :doc:`aql` queries) return
-server-side :ref:`Cursor` objects to batch the network communication between
-ArangoDB server and the client. Each request from the cursor fetches the next
-set of documents, where the total number of documents in the result set may or
-may not be known in advance depending on the query.
-
-For more information on the HTTP REST API for cursors visit this
+:ref:`Cursor` objects to batch the network communication between the ArangoDB
+server and the client. Each request from the cursor fetches the next set of
+documents, where the total number of documents in the result set may or may not
+be known in advance depending on the query. For more information on the HTTP
+REST API for using cursors visit this
 `page <https://docs.arangodb.com/HTTP/AqlQueryCursor/AccessingCursors.html>`__.
 
 .. note::

docs/database.rst

@@ -1,11 +1,11 @@
 Databases
 ---------
 
-A single ArangoDB instance can house multiple databases. Each database can have
-its own set of collections, graphs, and dedicated worker processes. There is
-always a default database named ``_system`` which cannot be dropped, can
-only be accessed with root privileges, and provides special operations for
-creating, deleting and enumerating other user defined databases.
+A single ArangoDB instance can house multiple databases. Each database in turn
+can have its own set of collections, graphs, and dedicated worker processes.
+There is always a default database named ``_system`` which cannot be dropped,
+can only be accessed with root privileges, and provides special operations for
+creating, deleting and enumerating other user-defined databases.
 
 For more information on the HTTP REST API for database management visit this
 `page <https://docs.arangodb.com/HTTP/Database/NotesOnDatabases.html>`_.
@@ -47,4 +47,4 @@ For more information on the HTTP REST API for database management visit this
 
 Refer to :ref:`ArangoClient` and :ref:`Database` classes for more details on
 the methods above, and the :doc:`user` page for more details on how to *add*,
-*update*, *replace* or *delete* database users.
+*update*, *replace* or *delete* database users separately

docs/document.rst

@@ -1,16 +1,17 @@
 Documents
 ---------
 
-**Documents** in python-arango are simply Python dictionaries. The documents
-can be nested to any depth and contain lists. Each document must contain the
+**Documents** in python-arango are Python dictionaries. The documents can be
+nested to an arbitrary depth and contain lists. Each document must have the
 ``"_key"`` field whose value identifies the document uniquely within a given
 collection. There is also the ``"_id"`` field whose value identifies the
 document uniquely across *all* collections within a given database, but this
-is completely optional in python-arango.
+field completely optional in python-arango documents.
 
-ArangoDB supports MVCC (Multiple Version Concurrency Control) and stores each
-document in multiple revisions. The document revision can be distinguished
-by value of the document's ``"_rev"`` field which is also not required.
+ArangoDB supports MVCC (Multiple Version Concurrency Control) and is capable
+of storing each document in multiple revisions. The document revision can be
+distinguished by value of the document's ``"_rev"`` field which is also not
+required in python-arango.
 
 **Here is an example of a valid document**:
 
@@ -32,11 +33,11 @@ by value of the document's ``"_rev"`` field which is also not required.
 
 .. _edge-documents:
 
-**Edge documents** or **edges** are similar to documents but with two more
+**Edge documents** or **edges** are similar to documents but with additional
 required fields ``"_from"`` and ``"_to"``. The value of these fields should be
-the value of a document's ``"_id"`` field. Edge documents are contained in
-:ref:`edge collections <edge-collections>`, which are sub-components of
-:doc:`graphs <graph>`.
+the value of a from and to vertices; ``"_id"`` fields. Edge documents are
+contained in :ref:`edge collections <edge-collections>`, which are components
+of :doc:`graphs <graph>`.
 
 **Here is an example of a valid edge document**:
 
@@ -53,11 +54,10 @@ the value of a document's ``"_id"`` field. Edge documents are contained in
     }
 
 For more information on document basics and terminologies visit this
-`page <https://docs.arangodb.com/HTTP/Document/AddressAndEtag.html>`__.
-For more information on the REST HTTP API for document management visit this
+`page <https://docs.arangodb.com/HTTP/Document/AddressAndEtag.html>`__ and
+for more information on the REST HTTP API for document management visit this
 `page <https://docs.arangodb.com/HTTP/Document/WorkingWithDocuments.html>`__.
 
-
 **Example:**
 
 .. code-block:: python

docs/errors.rst

@@ -6,7 +6,7 @@ which lightly wraps around the HTTP error responses returned from ArangoDB.
 Most of the error messages returned by python-arango come directly from the
 ArangoDB server.
 
-**Here is an example for catching and introspecting an exception:**
+**Here is an example of catching and introspecting an exception:**
 
 .. code-block:: python
 

docs/graph.rst

@@ -1,11 +1,11 @@
 Graphs
 ------
 
-A graph consists of **vertices** and **edges**. Edges are stored as documents
-in :ref:`edge collections <edge-collections>`, whereas vertices are stored as
-documents in :ref:`vertex collections <vertex-collections>` (edges can be used
-as vertices as well). The combination of edge and vertex collections used in a
-particular graph is defined via :ref:`edge definitions <edge-definitions>`. For
+An ArangoDB **graph** consists of **vertices** and **edges**. Edges are stored
+as documents in :ref:`edge collections <edge-collections>`, whereas vertices
+are stored as documents in :ref:`vertex collections <vertex-collections>`
+(edges can be vertices also). The combination of edge and vertex collections
+involved in a graph is defined :ref:`edge definitions <edge-definitions>`. For
 more general information on graphs, vertices and edges refer to this
 `page <https://docs.arangodb.com/Manual/Graphs>`__.
 
@@ -42,8 +42,8 @@ types of collections.
 
 The documents in a vertex collection are fully accessible from a standard
 collection. Managing documents through a vertex collection, however, adds
-additional *guarantees*: all modifications are executed in transactions and if
-a vertex is deleted all connected edges are also deleted.
+additional *guarantees*: all modifications are executed in transactions, and
+if a vertex is deleted all connected edges are also deleted automatically.
 
 For more information on the HTTP REST API for vertices and vertex collections
 refer to this `page <https://docs.arangodb.com/HTTP/Gharial/Vertices.html>`__.
@@ -92,8 +92,8 @@ a particular graph (see example below).
 
 .. _edge-collections:
 
-An **edge collection** consists of edge documents. Same as a vertex collection
-it is uniquely identified by its name, which must consist only of alphanumeric
+An **edge collection** consists of edge documents. Same as vertex collections
+it is uniquely identified by its name which must consist only of alphanumeric
 characters, hyphen and the underscore characters. Edge collections share their
 namespace with other types of collections.
 
@@ -102,7 +102,7 @@ collection. Managing documents through an edge collection, however, adds
 additional *guarantees*: all modifications are executed in transactions and
 edge documents are checked against the edge definitions on *insert*.
 
-For more information the HTTP REST API for edge definitions and collections
+For more information on the HTTP REST API for edge definitions and collections
 refer to this `page <https://docs.arangodb.com/HTTP/Gharial/Edges.html>`__.
 
 **Example:**
@@ -151,12 +151,11 @@ the methods above.
 Graph Traversals
 ================
 
-**Graph traversals**, which are executed on the server, can be initiated using
+**Graph traversals** (which are executed on the server) can be initiated using
 the :func:`~arango.graph.Graph.traverse` method in python-arango. A traversal
-can span across multiple vertex collections through a single edge collection,
-and walk over the documents in a variety of ways (see example below).
-
-For more information the HTTP REST API for graph traversals refer to this
+can span across multiple vertex collections but only a single edge collection,
+and walk over the documents in a variety of ways (see example below). For more
+information on the HTTP REST API for executing graph traversals refer to this
 `page <https://docs.arangodb.com/HTTP/Traversal/index.html>`__.
 
 **Example:**

docs/index.rst

@@ -1,12 +1,11 @@
 Indexes
 -------
 
-**Indexes** can be added to collections to speed up access to documents. Every
-collection has a primary hash index on its ``"_key"`` field by default. This
+**Indexes** can be added to collections to speed up document access. Every
+collection has a primary hash index on the ``"_key"`` field by default. This
 index cannot be deleted or modified. In addition, every edge collection has a
-special *edge* index on fields ``"_from"`` and ``"_to"``.
-
-For more information on the HTTP REST API for collection indexes visit this
+special *edge* index on fields ``"_from"`` and ``"_to"``. For more information
+on the HTTP REST API for collection index management visit this
 `page <https://docs.arangodb.com/HTTP/Indexes>`__.
 
 **Example:**

docs/task.rst

@@ -3,9 +3,8 @@ Task Management
 
 ArangoDB can execute user-defined Javascript snippets as *one-shot* (run only
 once without repeats) or *periodic* (re-scheduled after each execution) tasks.
-The tasks are executed in the context of the database they are defined in.
-
-For more information on the HTTP REST API for task management visit this
+The tasks are executed in the context of the database they are defined in. For
+more information on the HTTP REST API for task management visit this
 `page <https://docs.arangodb.com/HTTP/Tasks>`__.
 
 .. note::

docs/transaction.rst

@@ -3,10 +3,8 @@ Transactions
 
 Python-arango provides partial support for **transactions**, where incoming
 requests are queued in client-side memory and executed as a single, logical
-unit of work (ACID compliant).
-
-For more information on the HTTP REST API for transactions visit this
-`page <https://docs.arangodb.com/HTTP/Transaction>`__.
+unit of work (ACID compliant). For more information on the HTTP REST API for
+transactions visit this `page <https://docs.arangodb.com/HTTP/Transaction>`__.
 
 .. note::
     Due to the limitations of ArangoDB's HTTP API, :ref:`Transaction` does

docs/user.rst

@@ -1,12 +1,10 @@
 User Management
 ---------------
 
-ArangoDB **users** can be added, modified or removed using python-arango.
+ArangoDB users can be easily created, modified or deleted using python-arango.
 Operations to grant or revoke user access to specific databases are provided
-as well.
-
-For more information on the HTTP REST API for user management visit this
-`page <https://docs.arangodb.com/HTTP/UserManagement>`__.
+as well. For more information on the HTTP REST API for user management visit
+this `page <https://docs.arangodb.com/HTTP/UserManagement>`__.
 
 .. note::
     Some operations in the example below require root privileges (i.e. the
@@ -42,4 +40,4 @@ For more information on the HTTP REST API for user management visit this
     # Delete an existing user
     client.delete_user(username='jill')
 
-Refer to :ref:`ArangoClient` class for details on the above methods.
+Refer to :ref:`ArangoClient` class for more details on the above methods.

docs/wal.rst

@@ -6,7 +6,9 @@ write operations executed on ArangoDB. It can be used to run data recovery
 after a server crash, or synchronize slave databases with master databases in
 setups with replications.
 
-For more general information on ArangoDB write-ahead logs visit this
+For more information on the HTTP REST API for write-ahead logs visit this
+`page <https://docs.arangodb.com/HTTP/MiscellaneousFunctions>`__ and for more
+general information visit this
 `page <https://docs.arangodb.com/Manual/Architecture/WriteAheadLog.html>`_.
 
 .. note::