Adding more documentation

README.md

@@ -17,7 +17,7 @@
 Python driver for [ArangoDB](https://www.arangodb.com), a scalable multi-model
 database natively supporting documents, graphs and search.
 
-This is the _asyncio_ alternative of the officially supported [python-arango](https://github.com/arangodb/python-arango)
+This is the _asyncio_ alternative of the [python-arango](https://github.com/arangodb/python-arango)
 driver.
 
 **Note: This project is still in active development, features might be added or removed.**

docs/aql.rst

@@ -8,3 +8,155 @@ operations such as creating or deleting :doc:`databases <database>`,
 information, refer to `ArangoDB manual`_.
 
 .. _ArangoDB manual: https://docs.arangodb.com
+
+AQL Queries
+===========
+
+AQL queries are invoked from AQL API wrapper. Executing queries returns
+:doc:`result cursors <cursor>`.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient, AQLQueryKillError
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Get the API wrapper for "students" collection.
+        students = db.collection("students")
+
+        # Insert some test documents into "students" collection.
+        await students.insert_many([
+            {"_key": "Abby", "age": 22},
+            {"_key": "John", "age": 18},
+            {"_key": "Mary", "age": 21}
+        ])
+
+        # Get the AQL API wrapper.
+        aql = db.aql
+
+        # Retrieve the execution plan without running the query.
+        plan = await aql.explain("FOR doc IN students RETURN doc")
+
+        # Validate the query without executing it.
+        validate = await aql.validate("FOR doc IN students RETURN doc")
+
+        # Execute the query
+        cursor = await db.aql.execute(
+          "FOR doc IN students FILTER doc.age < @value RETURN doc",
+          bind_vars={"value": 19}
+        )
+
+        # Iterate through the result cursor
+        student_keys = []
+        async for doc in cursor:
+            student_keys.append(doc)
+
+        # List currently running queries.
+        queries = await aql.queries()
+
+        # List any slow queries.
+        slow_queries = await aql.slow_queries()
+
+        # Clear slow AQL queries if any.
+        await aql.clear_slow_queries()
+
+        # Retrieve AQL query tracking properties.
+        await aql.tracking()
+
+        # Configure AQL query tracking properties.
+        await aql.set_tracking(
+            max_slow_queries=10,
+            track_bind_vars=True,
+            track_slow_queries=True
+        )
+
+        # Kill a running query (this should fail due to invalid ID).
+        try:
+            await aql.kill("some_query_id")
+        except AQLQueryKillError as err:
+            assert err.http_code == 404
+
+See :class:`arangoasync.aql.AQL` for API specification.
+
+
+AQL User Functions
+==================
+
+**AQL User Functions** are custom functions you define in Javascript to extend
+AQL functionality. They are somewhat similar to SQL procedures.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Get the AQL API wrapper.
+        aql = db.aql
+
+        # Create a new AQL user function.
+        await aql.create_function(
+            # Grouping by name prefix is supported.
+            name="functions::temperature::converter",
+            code="function (celsius) { return celsius * 1.8 + 32; }"
+        )
+
+        # List AQL user functions.
+        functions = await aql.functions()
+
+        # Delete an existing AQL user function.
+        await aql.delete_function("functions::temperature::converter")
+
+See :class:`arangoasync.aql.AQL` for API specification.
+
+
+AQL Query Cache
+===============
+
+**AQL Query Cache** is used to minimize redundant calculation of the same query
+results. It is useful when read queries are issued frequently and write queries
+are not.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Get the AQL API wrapper.
+        aql = db.aql
+
+        # Retrieve AQL query cache properties.
+        await aql.cache.properties()
+
+        # Configure AQL query cache properties
+        await aql.cache.configure(mode="demand", max_results=10000)
+
+        # Clear results in AQL query cache.
+        await aql.cache.clear()
+
+See :class:`arangoasync.aql.AQLQueryCache` for API specification.

docs/cursor.rst

@@ -0,0 +1,8 @@
+Cursors
+-------
+
+Many operations provided by python-arango-async (e.g. executing :doc:`aql` queries)
+return result **cursors** to batch the network communication between ArangoDB
+server and python-arango-async client. Each HTTP request from a cursor fetches the
+next batch of results (usually documents). Depending on the query, the total
+number of items in the result set may or may not be known in advance.

docs/errors.rst

@@ -16,5 +16,18 @@ Client Errors
 =============
 
 :class:`arangoasync.exceptions.ArangoClientError` exceptions originate from
-python-arango client itself. They do not contain error codes nor HTTP request
+python-arango-async client itself. They do not contain error codes nor HTTP request
 response details.
+
+**Example**
+
+.. code-block:: python
+
+    from arangoasync.exceptions import ArangoClientError, ArangoServerError
+
+    try:
+        # Some operation that raises an error
+    except ArangoClientError:
+        # An error occurred on the client side
+    except ArangoServerError:
+        # An error occurred on the server side

docs/index.rst

@@ -63,6 +63,7 @@ Miscellaneous
 .. toctree::
     :maxdepth: 1
 
+    cursor
     errors
     errno