Documentation updates

Author: elprans

docs/examples.rst

@@ -0,0 +1,47 @@
+.. _asyncpg-examples:
+
+
+Usage Examples
+==============
+
+Below is an example of how **asyncpg** can be used to implement a simple
+Web service that computes the requested power of two.
+
+
+.. code-block:: python
+
+    import asyncio
+    import asyncpg
+    from aiohttp import web
+
+
+    async def handle(request):
+        """Handle incoming requests."""
+        pool = request.app['pool']
+        power = int(request.match_info.get('power', 10))
+
+        # Take a connection from the pool.
+        async with pool.acquire() as connection:
+            # Open a transaction.
+            async with connection.transaction():
+                # Run the query passing the request argument.
+                result = await connection.fetchval('select 2 ^ $1', power)
+                return web.Response(
+                    text="2 ^ {} is {}".format(power, result))
+
+
+    async def init_app():
+        """Initialize the application server."""
+        app = web.Application()
+        # Create a database connection pool
+        app['pool'] = await asyncpg.create_pool(database='postgres',
+                                                user='postgres')
+        # Configure service routes
+        app.router.add_route('GET', '/{power:\d+}', handle)
+        app.router.add_route('GET', '/', handle)
+        return app
+
+
+    loop = asyncio.get_event_loop()
+    app = loop.run_until_complete(init_app())
+    web.run_app(app)

docs/index.rst

@@ -5,6 +5,7 @@
     :target: https://pypi.python.org/pypi/asyncpg
 
 
+=======
 asyncpg
 =======
 
@@ -13,11 +14,16 @@ PostgreSQL and Python/asyncio.  asyncpg is an efficient, clean implementation
 of PostgreSQL server binary protocol for use with Python's ``asyncio``
 framework.
 
+**asyncpg** is a C extension and it is only currently compatible with
+CPython 3.5.
+
 
 Contents
 --------
 
 .. toctree::
    :maxdepth: 2
 
+   installation
+   examples
    api/index

docs/installation.rst

@@ -0,0 +1,57 @@
+.. _asyncpg-installation:
+
+
+Installation
+============
+
+**asyncpg** has no external dependencies and the recommended way to
+install it is to use **pip**:
+
+.. code-block:: bash
+
+    $ pip install asyncpg
+
+
+.. note::
+
+   It is recommended to use **pip** version **8.1** or later to take
+   advantage of the precompiled wheel packages.  Older versions of pip
+   will ignore the wheel packages and install asyncpg from the source
+   package.  In that case a working C compiler is required.
+
+
+Building from source
+--------------------
+
+If you want to build **asyncpg** from a Git checkout you will need:
+
+  * A working C compiler.
+  * CPython header files.  These can usually be obtained by installing
+    the relevant Python development package: **python3-dev** on Debian/Ubuntu,
+    **python3-devel** on RHEL/Fedora.
+  * Cython version 0.24 or later.  The easiest way to install it to use
+    virtualenv and pip, however a system package should also suffice.
+  * GNU make
+
+Once the above requirements are satisfied, run:
+
+.. code-block:: bash
+
+    $ make
+
+At this point you can run the usual ``setup.py`` commands or
+``pip install -e .`` to install the newly built version.
+
+.. note::
+
+   A debug build can be created by running ``make debug``.
+
+
+Running tests
+-------------
+
+To execute the testsuite simply run:
+
+.. code-block:: bash
+
+    $ make test