Completed user documentation

Author: apetenchea

docs/user.rst

@@ -1,5 +1,93 @@
 Users and Permissions
 ---------------------
 
-Python-arango provides operations for managing users and permissions. Most of
+ArangoDB provides operations for managing users and permissions. Most of
 these operations can only be performed by admin users via ``_system`` database.
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+    from arangoasync.typings import UserInfo
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "_system" database as root user.
+        sys_db = await client.db("_system", auth=auth)
+
+        # List all users.
+        users = await sys_db.users()
+
+        johndoe = UserInfo(
+            user="johndoe@gmail.com",
+            password="first_password",
+            active=True,
+            extra={"team": "backend", "title": "engineer"}
+        )
+
+        # Create a new user.
+        await sys_db.create_user(johndoe)
+
+        # Check if a user exists.
+        assert await sys_db.has_user(johndoe.user) is True
+        assert await sys_db.has_user("johndoe@gmail.com") is True
+
+        # Retrieve details of a user.
+        user_info = await sys_db.user(johndoe.user)
+        assert user_info.user == "johndoe@gmail.com"
+
+        # Update an existing user.
+        johndoe["password"] = "second_password"
+        await sys_db.update_user(johndoe)
+
+        # Replace an existing user.
+        johndoe["password"] = "third_password"
+        await sys_db.replace_user(johndoe)
+
+        # Retrieve user permissions for all databases and collections.
+        await sys_db.permissions(johndoe.user)
+
+        # Retrieve user permission for "test" database.
+        perm = await sys_db.permission(
+            username="johndoe@gmail.com",
+            database="test"
+        )
+
+        # Retrieve user permission for "students" collection in "test" database.
+        perm = await sys_db.permission(
+            username="johndoe@gmail.com",
+            database="test",
+            collection="students"
+        )
+
+        # Update user permission for "test" database.
+        await sys_db.update_permission(
+            username="johndoe@gmail.com",
+            permission="rw",
+            database="test"
+        )
+
+        # Update user permission for "students" collection in "test" database.
+        await sys_db.update_permission(
+            username="johndoe@gmail.com",
+            permission="ro",
+            database="test",
+            collection="students"
+        )
+
+        # Reset user permission for "test" database.
+        await sys_db.reset_permission(
+            username="johndoe@gmail.com",
+            database="test"
+        )
+
+        # Reset user permission for "students" collection in "test" database.
+        await sys_db.reset_permission(
+            username="johndoe@gmail.com",
+            database="test",
+            collection="students"
+        )
+
+See :class:`arangoasync.database.StandardDatabase` for API specification.