More info in Zaqar config-ref storage options

This patch adds some important information about zaqar's (Message
service) storage options:

1. The information about which storage options are active depending on
the chosen storage back end.
2. The general information about storage pipelines.
3. Currently possible values (stages) for each one of the storage
pipelines.
4. The information on how to enable notifications feature of zaqar.
5. A brief information about possibility to add external stages to the
storage pipelines.

Some typos are fixed by patch:
In some articles the word "backend" is replaced to "back end".

Change-Id: Iffc9ea9dcefdb76e15554e9223e9e8dbbe8288cd
Closes-Bug: 1534852

doc/config-reference/source/messaging.rst

@@ -11,6 +11,7 @@ Message service
    messaging/zaqar-drivers.rst
    messaging/zaqar-storage-drivers.rst
    messaging/zaqar-transport-drivers.rst
+   messaging/zaqar-notifications.rst
    messaging/zaqar-authentication.rst
    messaging/zaqar-pooling.rst
    messaging/zaqar-cache.rst

doc/config-reference/source/messaging/zaqar-notifications.rst

@@ -0,0 +1,16 @@
+=====================
+Notifications options
+=====================
+
+The notifications feature in the Message service can be enabled by adding
+``zaqar.notification.notifier`` stage to the message storage layer pipeline. To
+do it, ensure that ``zaqar.notification.notifier`` is added to
+``message_pipeline`` option in the ``[storage]`` section of ``zaqar.conf``:
+
+.. code-block:: ini
+
+   [storage]
+   message_pipeline = zaqar.notification.notifier
+
+For more information about storage layer pipelines, see
+:doc:`zaqar-storage-drivers`.

doc/config-reference/source/messaging/zaqar-pooling.rst

@@ -5,7 +5,7 @@ Pooling options
 The Message service supports pooling.
 
 Pooling aims to make the Message service highly scalable without losing any of
-its flexibility by allowing users to use multiple-backends.
+its flexibility by allowing users to use multiple back ends.
 
 You can enable and configure pooling with the following options:
 

doc/config-reference/source/messaging/zaqar-storage-drivers.rst

@@ -2,11 +2,57 @@
 Storage drivers options
 =======================
 
-The Message service supports several different backends for storing messages
-and their metadata. The recommended storage backend is MongoDB. The following
-tables detail the available options:
+Storage back ends
+~~~~~~~~~~~~~~~~~
+
+The Message service supports several different storage back ends (storage
+drivers) for storing management information, messages and their metadata. The
+recommended storage back end is MongoDB. For information on how to specify the
+storage back ends, see :doc:`messaging/zaqar-drivers`.
+
+When the storage back end is chosen, the corresponding back-end options become
+active. For example, if Redis is chosen as the management storage back end, the
+options in ``[drivers:management_store:redis]`` section become active.
+
+Storage layer pipelines
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A pipeline is a set of stages needed to process a request. When a new request
+comes to the Message service, first it goes through the transport layer
+pipeline and then through one of the storage layer pipelines depending on the
+type of operation of each particular request. For example, if the Message
+service receives a request to make a queue-related operation, the storage
+layer pipeline will be ``queue pipeline``. The Message service always has the
+actual storage controller as the final storage layer pipeline stage.
+
+By setting the options in the ``[storage]`` section of ``zaqar.conf``,
+you can add additional stages to these storage layer pipelines:
+
+* **Claim pipeline**
+* **Message pipeline** with built-in stage available to use:
+
+  * ``zaqar.notification.notifier`` - sends notifications to the queue
+    subscribers on each incoming message to the queue, in other words, enables
+    notifications functionality.
+* **Queue pipeline**
+* **Subscription pipeline**
+
+The storage layer pipelines options are empty by default, because additional
+stages can affect the performance of the Message service. Depending on the
+stages, the sequence in which the option values are listed does matter or not.
+
+You can add external stages to the storage layer pipelines. For information how
+to write and add your own external stages, see
+`Writing stages for the storage pipelines`_ tutorial.
+
+Options
+~~~~~~~
+
+The following tables detail the available options:
 
 .. include:: ../tables/zaqar-storage.rst
 .. include:: ../tables/zaqar-mongodb.rst
 .. include:: ../tables/zaqar-redis.rst
 .. include:: ../tables/zaqar-sqlalchemy.rst
+
+.. _`Writing stages for the storage pipelines` : http://docs.openstack.org/developer/zaqar/writing_pipeline_stages.html

tools/autogenerate-config-flagmappings/zaqar.flagmappings

@@ -16,7 +16,6 @@ logging_debug_format_suffix logging
 logging_default_format_string logging
 logging_exception_prefix logging
 logging_user_identity_format logging
-memcached_servers auth_token
 pooling pooling
 publish_errors logging
 syslog_log_facility logging