From 0097597f6c6bcce017266b9931ed0df3db752d56 Mon Sep 17 00:00:00 2001
From: Flavio Percoco <flaper87@gmail.com>
Date: Fri, 3 Oct 2014 13:33:27 +0200
Subject: [PATCH] Document mongodb's driver deployments

This patch adds a base documentation for mongodb's driver. This
documentation is useful for both users, developers and operators, and it
should be probably moved to the users-guide.

Lets work and brainstorm on it as a developers doc first and then move
it.

Change-Id: I532c3d5edf20497eb9eae1f691dd706c5fe10b2a
---
 doc/source/index.rst                        |  2 +-
 doc/source/{storage.rst => storage/api.rst} |  6 +--
 doc/source/storage/autoindex.rst            | 12 ++++++
 doc/source/storage/mongodb.rst              |  5 +++
 zaqar/queues/storage/mongodb/__init__.py    | 45 ++++++++++++++++++++-
 5 files changed, 65 insertions(+), 5 deletions(-)
 rename doc/source/{storage.rst => storage/api.rst} (75%)
 create mode 100644 doc/source/storage/autoindex.rst
 create mode 100644 doc/source/storage/mongodb.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6f5cbe9fa..be3a40fa6 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -89,7 +89,7 @@ Zaqar is composed of two layers:
    :maxdepth: 1
 
    transport
-   storage
+   storage/autoindex
 
 The **transport drivers** are responsible for interacting with Zaqar clients.
 Every query made by clients is processed by the transport layer,
diff --git a/doc/source/storage.rst b/doc/source/storage/api.rst
similarity index 75%
rename from doc/source/storage.rst
rename to doc/source/storage/api.rst
index 44a1b72fa..99ab0a4ae 100644
--- a/doc/source/storage.rst
+++ b/doc/source/storage/api.rst
@@ -1,6 +1,6 @@
--------
-Storage
--------
+---------------------------------
+API reference for storage drivers
+---------------------------------
 
 .. currentmodule:: zaqar.queues.storage.base
 
diff --git a/doc/source/storage/autoindex.rst b/doc/source/storage/autoindex.rst
new file mode 100644
index 000000000..0fefd2566
--- /dev/null
+++ b/doc/source/storage/autoindex.rst
@@ -0,0 +1,12 @@
+-------------
+Storage Layer
+-------------
+
+The **storage drivers** are responsible for interacting with the storage backends
+and, that way, store or retrieve the data coming from the transport layer.
+
+.. toctree::
+   :maxdepth: 1
+
+   api
+   mongodb
diff --git a/doc/source/storage/mongodb.rst b/doc/source/storage/mongodb.rst
new file mode 100644
index 000000000..7f68f0118
--- /dev/null
+++ b/doc/source/storage/mongodb.rst
@@ -0,0 +1,5 @@
+--------------
+MongoDB Driver
+--------------
+
+.. automodule:: zaqar.queues.storage.mongodb
diff --git a/zaqar/queues/storage/mongodb/__init__.py b/zaqar/queues/storage/mongodb/__init__.py
index 0a8037bdd..7c55a2f8c 100644
--- a/zaqar/queues/storage/mongodb/__init__.py
+++ b/zaqar/queues/storage/mongodb/__init__.py
@@ -11,7 +11,50 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""MongoDB Storage Driver for Zaqar"""
+r"""
+MongoDB Storage Driver for Zaqar.
+
+About the store
+---------------
+
+MongoDB is a nosql, eventually consistent, reliable database with support for
+horizontal-scaling and capable of handling different levels of throughputs.
+
+Supported Features
+------------------
+
+- FIFO
+- Unlimited horizontal-scaling [1]_
+- Reliability [2]_
+
+.. [1] This is only possible with a sharding environment
+.. [2] Write concern must be equal or higher than 2
+
+Supported Deployments
+---------------------
+
+MongoDB can be deployed in 3 different ways. The first and most simple one is
+to deploy a standalone `mongod` node. The second one is to use a Replica Sets
+which gives a master-slave deployment but cannot be scaled unlimitedly. The
+third and last one is a sharded cluster.
+
+The second and third methods are the ones recommended for production
+environments where durability and scalability are a must-have. The driver
+itself forces operators to use such environments by checking whether it is
+talking to a replica-set or sharded cluster. Such enforcement can be disabled
+by running Zaqar in an unreliable mode.
+
+Replica Sets
+------------
+
+When running on a replica-set, Zaqar won't try to be smart and it'll rely as
+much as possible on the database and pymongo.
+
+Sharded Cluster
+---------------
+
+TBD
+"""
 
 from zaqar.queues.storage.mongodb import driver