fixed #5

docs/index.rst

@@ -7,7 +7,8 @@ Welcome to CoolAMQP's documentation!
 
     whatsnew
     cluster
-    tutorial
+    tutorials/send_and_receive
+    how-to-guide
     caveats
     frames
     basics

docs/tutorials/send_and_receive.rst

+Send and receive
+================
+
+In this tutorial we'll learn how to declare a named queue and send a message to it with acknowledgement:
+
+First we need to connect to the server. Let's assume you have configured a virtual host called /vhost
+
+.. code-block:: python
+
+    from coolamqp.cluster import Cluster
+    from coolamqp.objects import NodeDefinition
+
+    nd = NodeDefinition('amqp://127.0.0.1:5672/vhost', user='test', password='test', heartbeat=30)
+    c = Cluster(nd)
+    c.start()
+
+Then we'll need to declare a queue:
+
+
+.. code-block:: python
+    from coolamqp.objects import Queue
+
+    queue = Queue('my-named-queue')
+    c.declare(queue).result()
+
+You'll be calling :code:`result()` on most of CoolAMQP's calls, as they return futures that complete when the task is done.
+Now let's try subscribing to this queue:
+
+.. code-block:: python
+
+    def handle_message(msg):
+        print(msg.body.tobytes().encode('utf-8'))
+        msg.ack()
+
+    cons, fut = c.consume(queue, no_ack=False, on_message=handle_message)
+    fut.result()
+
+Notice the :code:`tobytes()`. This is because CoolAMQP by default returns most of it's received bytes as memoryviews,
+for speed's sake.
+
+Also, your message handler is executed within the CoolAMQP's connection thread, so don't block for too long.
+
+Now it's time to send a message:
+
+.. code-block:: python
+
+    from coolamqp.objects import Message
+    c.publish(Message(b'my bag of bytes'), confirm=True).result()
+
+Without the confirm flag, publish would not return the future.
+
+Congratulations, you've just send and received a message! Now it's time to do some cleanup. First, we cancel the consumer,
+and then disconnect from the server
+
+.. code-block:: python
+
+    cons.cancel().result()
+    c.shutdown()
+