Several updates on documentation

docs/source/changelog.rst

@@ -0,0 +1,4 @@
+Changelog
+=========
+
+.. include:: ../../CHANGES.rst

docs/source/development/installation.rst

@@ -33,12 +33,14 @@ Generating documentation::
     $ make html
 
 
-To configure AWS access, check `boto3 configuration`_ or export::
+To configure AWS access, check `boto3 configuration`_ or export  (see `boto3 envvars`_)::
 
     $ export AWS_ACCESS_KEY_ID=<key>
     $ export AWS_SECRET_ACCESS_KEY=<secret>
+    $ export AWS_DEFAULT_REGION=sa-east-1  # for example
 
 
 .. _boto3 configuration: https://boto3.readthedocs.org/en/latest/guide/quickstart.html#configuration
+.. _boto3 envvars: http://boto3.readthedocs.org/en/latest/guide/configuration.html#environment-variable-configuration
 
 Check the :doc:`../settings` section to see specific configurations.

docs/source/faq.rst

@@ -1,16 +1,8 @@
 FAQ
 ---
 
-1. Loafer raises ImportError on my handler.
 
-   Check for typos and validate that your module can be imported in python
-   interpreter.
-
-   Also, you might need to add your project to ``PYTHONPATH`` envrironment
-   variable or ``sys.path``.
-
-
-2. How do I run I/O blocking code that's not a coroutine ?
+**1. How do I run I/O blocking code that's not a coroutine ?**
 
    Any code that is blocking and not a coroutine could run in a separate thread.
 

docs/source/handlers.rst

@@ -20,7 +20,18 @@ can also be used, but will run in a thread, outside the event loop.
 The ``handler`` does not need to return anything, but any unhandled error
 will cause the message to be ignored.
 
-You can specify the message to be rejected (and acknowledged) by explicity raising
-``RejectMessage``, see :doc:`exceptions` for details.
+Note that, if the ``handler`` silently failed, for example, if you do::
+
+    async def my_handler(message):
+        try:
+            ... some code ...
+        except Exception:
+            pass
+
+This will cause the message to be always acknowledged.
+
+You can specify the message to be ignored by explicity raising ``IgnoreMessage``,
+then the message will not be deleted, see :doc:`exceptions` for details.
+
 
 Successfull executions of ``handler`` will acknowledge (delete) the message.

docs/source/index.rst

@@ -50,5 +50,6 @@ Other
 .. toctree::
     :maxdepth: 2
 
-    tutorial.rst
+    ..tutorial.rst
     faq.rst
+    changelog.rst

docs/source/message_translators.rst

@@ -14,15 +14,24 @@ Implementation
 
 The message translator class should implement the method ``translate`` like::
 
-    def translate(self, message):
+    class MyMessageTranslator(object):
+
+        def translate(self, message):
+            return {'content': int(message)}
 
 And it should return a dictionary in the format::
 
     return {'content': processed_message}
 
 The ``processed_message`` is the message delivered to ``handler``.
 
+In the example above, message is supposed to be an integer and will be
+delivered as integer too.
+
+The ``message`` parameter in ``def translate`` is always a string object.
+
 If ``processed_message`` is ``None`` the message will be ignored and not
 acknowledged.
 
-Unhandled errors also makes the message to be ignored.
+Unhandled errors also makes the message to be ignored, but it's a good practice
+to handle those errors.

docs/source/quickstart/usage.rst

@@ -13,15 +13,15 @@ Examples
 
     $ loafer
 
-* Add ``source`` and ``handler`` parameters::
+* Add ``source`` and ``handler`` parameters (all parameters are optional)::
 
   $ loafer --source my-queue-name --handler loafer.example.jobs.async_example_job
 
 
 * Publishing a message to SNS/SQS (you should see some logging messages)::
 
     # To SQS
-    $ loafer publish --queue a-queue-name --msg 'foobar'
+    $ loafer publish_sqs --queue a-queue-name --msg 'foobar'
 
     # To SNS (considering, the queue we consume are subscribed to topic)
-    $ loafer publish --topic a-topic-name --msg 'foobar'
+    $ loafer publish_sns --topic a-topic-name --msg 'foobar'