Update documentation

CONTRIBUTING.rst

@@ -101,7 +101,7 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check
+3. The pull request should work for Python 2.7 and 3.5. Check
    https://travis-ci.org/jcollado/rabbithole/pull_requests
    and make sure that the tests pass for all supported Python versions.
 

README.rst

@@ -36,7 +36,9 @@ Store messages from rabbitmq into a SQL database
 Features
 --------
 
-* TODO
+* Get messages from multiple RabbitMQ exchanges
+* Group messages in batches
+* Write message batches to a SQL database
 
 Credits
 ---------

docs/index.rst

@@ -10,7 +10,8 @@ Contents:
    installation
    usage
    contributing
-   authorshistory
+   authors
+   history
 
 Indices and tables
 ==================

docs/modules.rst

@@ -0,0 +1,7 @@
+rabbithole
+==========
+
+.. toctree::
+   :maxdepth: 4
+
+   rabbithole

docs/rabbithole.rst

@@ -0,0 +1,46 @@
+rabbithole package
+==================
+
+Submodules
+----------
+
+rabbithole.batcher module
+-------------------------
+
+.. automodule:: rabbithole.batcher
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+rabbithole.cli module
+---------------------
+
+.. automodule:: rabbithole.cli
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+rabbithole.consumer module
+--------------------------
+
+.. automodule:: rabbithole.consumer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+rabbithole.db module
+--------------------
+
+.. automodule:: rabbithole.db
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: rabbithole
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/usage.rst

@@ -2,6 +2,72 @@
 Usage
 =====
 
-To use Rabbit Hole in a project::
+CLI
+===
 
-    import rabbithole
+Rabbit Hole is a command line tool that has been written as a lightweight
+alternative to logstash_ for the specific use case in which the *input* is
+*rabbitmq* and the *output* is a SQL database.
+
+It can be executed from the command line like this::
+
+    $ rabbithole config.yml
+
+where *config.yml* is a YAML configuration file. For example:
+
+.. code-block:: yaml
+
+    size_limit: 5
+    time_limit: 15
+    rabbitmq: '172.20.0.2'
+    database: 'postgres://postgres@172.20.0.3/database'
+    output:
+      logs:
+        INSERT INTO logs (message, message_vector)
+        VALUES (:message, to_tsvector('english', :message))
+      events:
+        INSERT INTO events (message, message_vector)
+        VALUES (:message, to_tsvector('english', :message))
+
+where:
+    - *size_limit*: batcher size limit
+    - *time_limit*: batcher size limit
+    - *rabbitmq*: RabbitMQ server address
+    - *database*: Database connection URL
+    - *output*: Mapping from RabbitMQ exchange names to SQL queries
+
+
+Building blocks
+===============
+
+Input
+-----
+
+RabbitMQ is assumed to be the messages input. What can be configured is the IP
+address of the server and the exchanges for which messages should be delivered
+specified as the keys of the *output* field.
+
+Batchers
+--------
+
+Rabbit Hole uses the concept of batchers that is also used in logstash_. A
+batcher is just an in-memory queue whose goal is to output data more
+efficiently by writing multiple messages at once.
+
+The batcher keeps messages in memory until its capacity has been filled up or
+until a time limit is exceeded. Both parameters can be set in the configuration
+file.
+
+Output
+------
+
+A SQL database is assumed to be the messages output. What can be configured is
+the `database URL`_ and the queries_ to execute for the messages received for
+each exchange. Note that the underlying implementation uses sqlalchemy_, so
+please refer to its documentation for more information about their format.
+
+
+.. _logstash: https://www.elastic.co/products/logstash
+.. _database URL: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
+.. _queries: http://docs.sqlalchemy.org/en/latest/core/sqlelement.html?highlight=text#sqlalchemy.sql.expression.text
+.. _sqlalchemy: http://www.sqlalchemy.org/