Migrate configuration docs

Co-Authored-By: wanghao<sxmatch1986@gmail.com>

Closes-bug: #1706193

Change-Id: Ib0145f9aaf4f498d236fb4a0beaa01aeb6379177

doc/source/conf.py

@@ -30,19 +30,29 @@ sys.path.insert(0, os.path.abspath('../../'))
 sys.path.insert(0, os.path.abspath('../'))
 sys.path.insert(0, os.path.abspath('./'))
 
+
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings.
 # They can be extensions coming with Sphinx (named 'sphinx.ext.*')
 # or your custom ones.
 
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.coverage',
+extensions = ['sphinx.ext.coverage',
               'sphinx.ext.ifconfig',
               'sphinx.ext.graphviz',
+              'stevedore.sphinxext',
+              'oslo_config.sphinxext',
+              'sphinx.ext.autodoc',
+              'sphinx.ext.viewcode',
+              'oslo_config.sphinxconfiggen',
               'openstackdocstheme',
               ]
 
+config_generator_config_file = [
+    ('../../etc/oslo-config-generator/zaqar.conf',
+     '_static/zaqar'),
+]
+
 # autodoc generation is a bit aggressive and a nuisance
 # when doing heavy text edit cycles. Execute "export SPHINX_DEBUG=1"
 # in your terminal to disable
@@ -153,7 +163,7 @@ html_theme_options = {}
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/source/configuration/configuring.rst

@@ -0,0 +1,188 @@
+.. _basic-configuration:
+
+Basic Configuration
+===================
+
+The ``zaqar.conf`` configuration file is an
+`INI file format <https://en.wikipedia.org/wiki/INI_file>`_.
+
+This file is located in ``/etc/zaqar``. If there is a file ``zaqar.conf`` in
+``~/.zaqar`` directory, it is used instead of the one in ``/etc/zaqar``
+directory. When you manually install the Message service, you must generate
+the zaqar.conf file using the config samples generator located inside Zaqar
+installation directory and customize it according to your preferences.
+
+To generate the sample configuration file ``zaqar/etc/zaqar.conf.sample``:
+
+.. code-block:: console
+
+   # pip install tox
+   $ cd zaqar
+   $ tox -e genconfig
+
+Where :samp:`{zaqar}` is your Message service installation directory.
+
+Then copy Message service configuration sample to the directory ``/etc/zaqar``:
+
+.. code-block:: console
+
+   # cp etc/zaqar.conf.sample /etc/zaqar/zaqar.conf
+
+For a list of configuration options, see the tables in this guide.
+
+.. important::
+
+   Do not specify quotes around configuration options.
+
+
+Message API configuration
+-------------------------
+
+The Message service has two APIs: the HTTP REST API for WSGI transport driver,
+and the Websocket API for Websocket transport driver. The Message service can
+use only one transport driver at the same time.
+
+The functionality and behavior of the APIs are defined by API versions. For
+example, the Websocket API v2 acts the same as the HTTP REST API v2. For now
+there are v1, v1.1 and v2 versions of HTTP REST API and only v2 version of
+Websocket API.
+
+Permission control options in each API version:
+
+* The v1 does not have any permission options.
+* The v1.1 has only ``admin_mode`` option which controls the global
+  permission to access the pools and flavors functionality.
+* The v2 has only:
+
+  * RBAC policy options: ``policy_default_rule``, ``policy_dirs``,
+    ``policy_file`` which controls the permissions to access each type of
+    functionality for different types of users.
+  * ``secret_key`` option which defines a secret key to use for signing
+    special URLs. These are called pre-signed URLs and give temporary
+    permissions to outsiders of the system.
+
+
+Authentication and authorization
+--------------------------------
+
+All requests to the API may only be performed by an authenticated agent.
+
+The preferred authentication system is the OpenStack Identity service,
+code-named keystone.
+
+Identity service authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To authenticate, an agent issues an authentication request to an Identity
+service endpoint. In response to valid credentials, Identity service responds
+with an authentication token and a service catalog that contains a list of
+all services and endpoints available for the given token.
+
+Multiple endpoints may be returned for Message service according to physical
+locations and performance/availability characteristics of different
+deployments.
+
+Normally, Identity service middleware provides the ``X-Project-Id`` header
+based on the authentication token submitted by the Message service client.
+
+For this to work, clients must specify a valid authentication token in the
+``X-Auth-Token`` header for each request to the Message service API. The API
+validates authentication tokens against Identity service before servicing each
+request.
+
+No authentication
+~~~~~~~~~~~~~~~~~
+
+If authentication is not enabled, clients must provide the ``X-Project-Id``
+header themselves.
+
+
+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
+
+
+
+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 back ends.
+
+
+
+Storage drivers 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.
+
+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
+<http://docs.openstack.org/developer/zaqar/writing_pipeline_stages.html>`_
+tutorial.
+
+
+Messaging log files
+-------------------
+
+The corresponding log file of each Messaging service is stored in the
+``/var/log/zaqar/`` directory of the host on which each service runs.
+
+.. list-table:: Log files used by Messaging services
+   :widths: 35 35
+   :header-rows: 1
+
+   * - Log filename
+     - Service that logs to the file
+   * - ``server.log``
+     - Messaging service
+

doc/source/configuration/index.rst

@@ -0,0 +1,18 @@
+.. _configuring:
+
+===================
+Configuration Guide
+===================
+
+This section provides a list of all possible options for each
+configuration file.  Refer to :ref:`basic-configuration` for a
+detailed guide in getting started with various option settings.
+
+Zaqar uses the following configuration files for its various services.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   *
+

doc/source/configuration/sample-configuration.rst

@@ -0,0 +1,18 @@
+.. _sample-configuration:
+
+==========================
+Zaqar Sample Configuration
+==========================
+
+The following are sample configuration files for all Zaqar services and
+utilities. These are generated from code and reflect the current state of code
+in the Zaqar repository.
+
+
+Sample configuration for Zaqar API
+----------------------------------
+
+This sample configuration can also be viewed in `zaqar.conf.sample
+<../_static/zaqar.conf.sample>`_.
+
+.. literalinclude:: ../_static/zaqar.conf.sample

doc/source/configuration/zaqar.rst

@@ -0,0 +1,9 @@
+.. _zaqar.conf:
+
+----------
+zaqar.conf
+----------
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/zaqar.conf
+

doc/source/index.rst

@@ -92,6 +92,7 @@ Contents
    user/index
    admin/index
    install/index
+   configuration/index
    contributor/index
 
 .. toctree::

etc/oslo-config-generator/zaqar.conf

@@ -1,6 +1,6 @@
 [DEFAULT]
+wrap_width = 80
 output_file = etc/zaqar.conf.sample
-namespace = zaqar.bootstrap
 namespace = zaqar.common.auth
 namespace = zaqar.common.configs
 namespace = zaqar.storage.pipeline
@@ -10,6 +10,7 @@ namespace = zaqar.storage.redis
 namespace = zaqar.storage.sqlalchemy
 namespace = zaqar.storage.swift
 namespace = zaqar.transport.wsgi
+namespace = zaqar.transport.websocket
 namespace = zaqar.transport.base
 namespace = zaqar.transport.validation
 namespace = keystonemiddleware.auth_token