From 19796a6f7c3cd9adfd6eb34b2393704410a91c3c Mon Sep 17 00:00:00 2001
From: gecong1973 <ge.cong@zte.com.cn>
Date: Thu, 8 Jun 2017 04:30:24 -0400
Subject: [PATCH] Add new command guide doc

All the zaqarclient command have been added according to 'openstack
messaging XXX' format,see [1] , this patch update doc accordingly.

[1] https://review.openstack.org/#/c/470201/

Change-Id: I552b0b95c960b17d25272c53863e16e191428da2
---
 doc/source/command/claim.rst        | 110 ++++++++++++++++-
 doc/source/command/pool.rst         | 140 ++++++++++++++++++++-
 doc/source/command/queue.rst        | 182 +++++++++++++++++++++++++++-
 doc/source/command/subscription.rst | 129 +++++++++++++++++++-
 4 files changed, 557 insertions(+), 4 deletions(-)

diff --git a/doc/source/command/claim.rst b/doc/source/command/claim.rst
index 8717b610..37dff856 100644
--- a/doc/source/command/claim.rst
+++ b/doc/source/command/claim.rst
@@ -7,14 +7,18 @@ For help on a specific :command:`openstack claim` command, enter:
 
    $ openstack claim COMMAND -h/--help
 
-The four commands:
+The eight commands:
 
 .. code-block:: console
 
       claim create
+      messaging claim create
       claim query
+      messaging claim query
       claim release
+      messaging claim release
       claim renew
+      messaging claim renew
 
 .. _openstack_claim_create:
 
@@ -48,6 +52,37 @@ Create claim and return a list of claimed messages.
 ``--limit <limit>``
   Claims a set of messages, up to limit.
 
+.. _openstack_messaging_claim_create:
+
+openstack messaging claim create
+----------------------
+
+.. code-block:: console
+
+   usage: openstack messaging claim create [-h] [-f {csv,json,table,value,yaml}]
+                                           [-c COLUMN] [--max-width <integer>] [--noindent]
+                                           [--quote {all,minimal,none,nonnumeric}]
+                                           [--ttl <ttl>] [--grace <grace>]
+                                           [--limit <limit>]
+                                           <queue_name>
+
+Create claim and return a list of claimed messages.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue to be claim.
+
+**Optional arguments:**
+
+``--ttl <ttl>``
+  Time to live in seconds for claim.
+
+``--grace <grace>``
+  The message grace period in seconds.
+
+``--limit <limit>``
+  Claims a set of messages, up to limit.
 
 .. _openstack_claim_query:
 
@@ -71,6 +106,29 @@ Display claim details.
 ``<claim_id>``
   ID of the claim.
 
+.. _openstack_messaging_claim_query:
+
+openstack messaging claim query
+---------------------
+
+.. code-block:: console
+
+   usage: openstack messaging claim query [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
+                                          [--max-width <integer>] [--noindent]
+                                          [--quote {all,minimal,none,nonnumeric}]
+                                          <queue_name> <claim_id>
+
+Display claim details.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the claimed queue.
+
+``<claim_id>``
+  ID of the claim.
+
+
 .. _openstack_claim_release:
 
 openstack claim release
@@ -84,6 +142,25 @@ Delete a claim.
 
 **Positional arguments:**
 
+``<queue_name>``
+  Name of the claimed queue.
+
+``<claim_id>``
+  Claim ID to delete.
+
+.. _openstack_messaging_claim_release:
+
+openstack messaging claim release
+-----------------------
+
+.. code-block:: console
+
+   usage: openstack messaging claim release [-h] <queue_name> <claim_id>
+
+Delete a claim.
+
+**Positional arguments:**
+
 ``<queue_name>``
   Name of the claimed queue.
 
@@ -120,3 +197,34 @@ Renew a claim.
 
 ``--grace <grace>``
   The message grace period in seconds.
+
+.. _openstack_messaging_claim_renew:
+
+openstack messaging claim renew
+---------------------
+
+.. code-block:: console
+
+   usage: openstack messaging claim renew [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
+                                          [--max-width <integer>] [--noindent]
+                                          [--quote {all,minimal,none,nonnumeric}]
+                                          [--ttl <ttl>] [--grace <grace>]
+                                          <queue_name> <claim_id>
+
+Renew a claim.
+
+**Positional arguments:**
+
+``<queue_name> ``
+  Name of the claimed queue.
+
+``<claim_id>``
+  Claim ID.
+
+**Optional arguments:**
+
+``--ttl <ttl>``
+  Time to live in seconds for claim.
+
+``--grace <grace>``
+  The message grace period in seconds.
diff --git a/doc/source/command/pool.rst b/doc/source/command/pool.rst
index e8747044..f38b2f7b 100644
--- a/doc/source/command/pool.rst
+++ b/doc/source/command/pool.rst
@@ -7,15 +7,20 @@ For help on a specific :command:`openstack pool` command, enter:
 
    $ openstack pool COMMAND -h/--help
 
-The five commands:
+The ten commands:
 
 .. code-block:: console
 
       pool create
+      messaging pool create
       pool delete
+      messaging pool delete
       pool list
+      messaging pool list
       pool show
+      messaging pool show
       pool update
+      messaging pool update
 
 .. _openstack_pool_create:
 
@@ -45,6 +50,41 @@ Create a pool.
 
 **Optional arguments:**
 
+``--pool_group <pool_group>``
+  Group of the pool.
+
+``--pool_options <pool_options>``
+  An optional request component related to
+  storage-specific options.
+
+.. _openstack_messaging_pool_create:
+
+openstack messaging pool create
+---------------------
+
+.. code-block:: console
+
+   usage: openstack messaging pool create [-h] [-f {json,shell,table,value,yaml}]
+                                          [-c COLUMN] [--max-width <integer>] [--noindent]
+                                          [--prefix PREFIX] [--pool_group <pool_group>]
+                                          [--pool_options <pool_options>]
+                                          <pool_name> <pool_uri> <pool_weight>
+
+Create a pool.
+
+**Positional arguments:**
+
+``<pool_name>``
+  Name of the pool.
+
+``<pool_uri>``
+  Storage engine URI.
+
+``<pool_weight>``
+  weight of the pool.
+
+**Optional arguments:**
+
 ``--pool_group <pool_group>``
   Group of the pool.
 
@@ -68,6 +108,21 @@ Delete a pool.
 ``<pool_name>``
   Name of the pool.
 
+.. _openstack_messaging_pool_delete:
+
+openstack messaging pool delete
+---------------------
+
+.. code-block:: console
+
+   usage: openstack messaging pool delete [-h] <pool_name>
+
+Delete a pool.
+
+**Positional arguments:**
+
+``<pool_name>``
+  Name of the pool.
 
 .. _openstack_pool_list:
 
@@ -86,6 +141,32 @@ List available Pools.
 
 **Optional arguments:**
 
+``--marker <pool_name>``
+  Pool's paging marker.
+
+``--limit <limit>``
+  Page size limit.
+
+``--detailed <detailed>``
+  Detailed output.
+
+.. _openstack_messaging_pool_list:
+
+openstack messaging pool list
+-------------------
+
+.. code-block:: console
+
+   usage: openstack messaging pool list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
+                                        [--max-width <integer>] [--noindent]
+                                        [--quote {all,minimal,none,nonnumeric}]
+                                        [--marker <pool_name>] [--limit <limit>]
+                                        [--detailed <detailed>]
+
+List available Pools.
+
+**Optional arguments:**
+
 ``--marker <pool_name>``
   Pool's paging marker.
 
@@ -111,6 +192,25 @@ Display pool details.
 
 **Positional arguments:**
 
+``<pool_name>``
+  Pool to display (name).
+
+.. _openstack_messaging_pool_show:
+
+openstack messaging pool show
+-------------------
+
+.. code-block:: console
+
+   usage: openstack messaging pool show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
+                                        [--max-width <integer>] [--noindent]
+                                        [--prefix PREFIX]
+                                        <pool_name>
+
+Display pool details.
+
+**Positional arguments:**
+
 ``<pool_name>``
   Pool to display (name).
 
@@ -150,3 +250,41 @@ Update a pool attribute.
 ``--pool_options <pool_options>``
   An optional request component related to
   storage-specific options.
+
+.. _openstack_messaging_pool_update:
+
+openstack messaging pool update
+---------------------
+
+.. code-block:: console
+
+   usage: openstack messaging pool update [-h] [-f {json,shell,table,value,yaml}]
+                                          [-c COLUMN] [--max-width <integer>] [--noindent]
+                                          [--prefix PREFIX] [--pool_uri <pool_uri>]
+                                          [--pool_weight <pool_weight>]
+                                          [--pool_group <pool_group>]
+                                          [--pool_options <pool_options>]
+                                          <pool_name>
+
+Update a pool attribute.
+
+**Positional arguments:**
+
+``<pool_name>``
+  Name of the pool.
+
+**Optional arguments:**
+
+``--pool_uri <pool_uri>``
+  Storage engine URI.
+
+``--pool_weight <pool_weight>``
+  Weight of the pool.
+
+``--pool_group <pool_group>``
+  Group of the pool.
+
+``--pool_options <pool_options>``
+  An optional request component related to
+  storage-specific options.
+
diff --git a/doc/source/command/queue.rst b/doc/source/command/queue.rst
index a6ae2f5b..b644d443 100644
--- a/doc/source/command/queue.rst
+++ b/doc/source/command/queue.rst
@@ -7,17 +7,24 @@ For help on a specific :command:`openstack queue` command, enter:
 
    $ openstack queue COMMAND -h/--help
 
-The seven commands:
+The fourteen commands:
 
 .. code-block:: console
 
       queue create
+      messaging queue create
       queue delete
+      messaging queue delete
       queue get metadata
+      messaging queue get metadata
       queue list
+      messaging queue list
       queue set metadata
+      messaging queue set metadata
       queue signed url
+      messaging queue signed url
       queue stats
+      messaging queue stats
 
 .. _openstack_queue_create:
 
@@ -38,6 +45,24 @@ Create a queue.
 ``<queue_name>``
   Name of the queue.
 
+.. _openstack_messaging_queue_create:
+
+openstack messaging queue create
+----------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue create [-h] [-f {json,shell,table,value,yaml}]
+                                           [-c COLUMN] [--max-width <integer>] [--noindent]
+                                           [--prefix PREFIX]
+                                           <queue_name>
+
+Create a queue.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
 
 .. _openstack_queue_delete:
 
@@ -55,6 +80,21 @@ Delete a queue.
 ``<queue_name>``
   Name of the queue.
 
+.. _openstack_messaging_queue_delete:
+
+openstack messaging queue delete
+----------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue delete [-h] <queue_name>
+
+Delete a queue.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
 
 .. _openstack_queue_get_metadata:
 
@@ -75,6 +115,24 @@ Get queue metadata.
 ``<queue_name>``
   Name of the queue.
 
+.. _openstack_messaging_queue_get_metadata:
+
+openstack messaging queue get metadata
+----------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue get metadata [-h] [-f {json,shell,table,value,yaml}]
+                                                 [-c COLUMN] [--max-width <integer>]
+                                                 [--noindent] [--prefix PREFIX]
+                                                 <queue_name>
+
+Get queue metadata.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
 
 .. _openstack_queue_list:
 
@@ -102,6 +160,31 @@ List available queues.
 ``--detailed``
   If show detailed information of queue.
 
+.. _openstack_messaging_queue_list:
+
+openstack messaging queue list
+--------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
+                                         [--max-width <integer>] [--noindent]
+                                         [--quote {all,minimal,none,nonnumeric}]
+                                         [--marker <queue_id>] [--limit <limit>]
+                                         [--detailed]
+
+List available queues.
+
+**Optional arguments:**
+
+``--marker <queue_id>``
+  Queue's paging marker.
+
+``--limit <limit>``
+  Page size limit.
+
+``--detailed``
+  If show detailed information of queue.
 
 .. _openstack_queue_set_metadata:
 
@@ -112,6 +195,25 @@ openstack queue set metadata
 
    usage: openstack queue set metadata [-h] <queue_name> <queue_metadata>
 
+Set queue metadata.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
+
+``<queue_metadata>``
+  Queue metadata. It should be json like. For example: '{"age": 18}'
+
+.. _openstack_messaging_queue_set_metadata:
+
+openstack messaging queue set metadata
+----------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue set metadata [-h] <queue_name> <queue_metadata>
+
 Set queue metadata.All the metadata of the queue will be replaced by 
 queue_metadata.
 
@@ -148,6 +250,41 @@ Create a pre-signed url for the queue.
 
 **Optional arguments:**
 
+``--paths <paths>``
+  Allowed paths in a comma-separated list.
+  Options: messages, subscriptions, claims.
+
+``--ttl-seconds <ttl_seconds>``
+  Length of time (in seconds) until the signature expires.
+
+``--methods <methods>``
+  HTTP methods to allow as a comma-separated list.
+  Options: GET, HEAD, OPTIONS, POST, PUT, DELETE.
+
+.. _openstack_messaging_queue_signed_url:
+
+openstack messaging queue signed url
+--------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue signed url [-h] [-f {json,shell,table,value,yaml}]
+                                               [-c COLUMN] [--max-width <integer>]
+                                               [--noindent] [--prefix PREFIX]
+                                               [--paths <paths>]
+                                               [--ttl-seconds <ttl_seconds>]
+                                               [--methods <methods>]
+                                               <queue_name>
+
+Create a pre-signed url for the queue.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
+
+**Optional arguments:**
+
 ``--paths <paths>``
   Allowed paths in a comma-separated list.
   Options: messages, subscriptions, claims.
@@ -179,6 +316,24 @@ Get queue stats.
 ``<queue_name>``
   Name of the queue.
 
+.. _openstack_messaging_queue_stats:
+
+openstack messaging queue stats
+---------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue stats [-h] [-f {json,shell,table,value,yaml}]
+                                          [-c COLUMN] [--max-width <integer>] [--noindent]
+                                          [--prefix PREFIX]
+                                          <queue_name>
+
+Get queue stats.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
 
 .. _openstack_queue_purge:
 
@@ -204,3 +359,28 @@ the queue will be purged by default.
 
 ``--resource_types <resource_types>`
   Resource types want to be purged. Support ``messages`` and ``subscriptions``.
+
+.. _openstack_messaging_queue_purge:
+
+openstack messaging queue purge
+---------------------
+
+.. code-block:: console
+
+   usage: openstack messaging queue purge [-h] [--resource_types <resource_types>]
+                                          <queue_name>
+
+Purge a queue. All the metadata of the queue will be kept. Use
+``--resource_types`` to specify which resource should be pured. If
+``--resource_types`` is not specified, all the messages and subscriptions in
+the queue will be purged by default.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
+
+**Optional arguments:**
+
+``--resource_types <resource_types>`
+  Resource types want to be purged. Support ``messages`` and ``subscriptions``.
diff --git a/doc/source/command/subscription.rst b/doc/source/command/subscription.rst
index ef86805a..dae268d9 100644
--- a/doc/source/command/subscription.rst
+++ b/doc/source/command/subscription.rst
@@ -7,15 +7,20 @@ For help on a specific :command:`openstack subscription` command, enter:
 
    $ openstack subscription COMMAND -h/--help
 
-The five commands:
+The ten commands:
 
 .. code-block:: console
 
       subscription create
+      messaging subscription create
       subscription delete
+      messaging subscription delete
       subscription list
+      messaging subscription list
       subscription show
+      messaging subscription show
       subscription update
+      messaging subscription update
 
 .. _openstack_subscription_create:
 
@@ -43,6 +48,31 @@ Create a subscription.
 ``<ttl>``
   Time to live of the subscription in seconds.
 
+.. _openstack_messaging_subscription_create:
+
+openstack messaging subscription create
+-----------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging subscription create [-h] [-f {json,shell,table,value,yaml}]
+                                                  [-c COLUMN] [--max-width <integer>]
+                                                  [--noindent] [--prefix PREFIX]
+                                                  [--options <options>]
+                                                  <queue_name> <subscriber> <ttl>
+
+Create a subscription.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
+
+``<subscriber>``
+  Subscriber which will be notified.
+
+``<ttl>``
+  Time to live of the subscription in seconds.
 
 .. _openstack_subscription_delete:
 
@@ -63,6 +93,24 @@ Delete a subscription.
 ``<subscription_id>``
   ID of the subscription.
 
+.. _openstack_messaging_subscription_delete:
+
+openstack messaging subscription delete
+-----------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging subscription delete [-h] <queue_name> <subscription_id>
+
+Delete a subscription.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
+
+``<subscription_id>``
+  ID of the subscription.
 
 .. _openstack_subscription_list:
 
@@ -86,6 +134,27 @@ Get list of subscriptions.
 ``<queue_name>``
   Name of the queue.
 
+.. _openstack_messaging_subscription_list:
+
+openstack messaging subscription list
+---------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging subscription list [-h] [-f {csv,json,table,value,yaml}]
+                                                [-c COLUMN] [--max-width <integer>]
+                                                [--noindent]
+                                                [--quote {all,minimal,none,nonnumeric}]
+                                                [--marker <subscription_id>]
+                                                [--limit <limit>]
+                                                <queue_name>
+
+Get list of subscriptions.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
 
 .. _openstack_subscription_show:
 
@@ -109,6 +178,27 @@ Query a subscription details.
 ``<subscription_id>``
   ID of the subscription.
 
+.. _openstack_messaging_subscription_show:
+
+openstack messaging subscription show
+---------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging subscription show [-h] [-f {json,shell,table,value,yaml}]
+                                                [-c COLUMN] [--max-width <integer>]
+                                                [--noindent] [--prefix PREFIX]
+                                                <queue_name> <subscription_id>
+
+Query a subscription details.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
+
+``<subscription_id>``
+  ID of the subscription.
 
 .. _openstack_subscription_update:
 
@@ -144,3 +234,40 @@ Update a subscription.
 
 ``--options <options>``
   Metadata of the subscription in JSON format.
+
+.. _openstack_messaging_subscription_update:
+
+openstack messaging subscription update
+-----------------------------
+
+.. code-block:: console
+
+   usage: openstack messaging subscription update [-h] [-f {json,shell,table,value,yaml}]
+                                                  [-c COLUMN] [--max-width <integer>]
+                                                  [--noindent] [--prefix PREFIX]
+                                                  [--subscriber <subscriber>] [--ttl <ttl>]
+                                                  [--options <options>]
+                                                  <queue_name> <subscription_id>
+
+Update a subscription.
+
+**Positional arguments:**
+
+``<queue_name>``
+  Name of the queue.
+
+``<subscription_id>``
+  ID of the subscription
+
+**Optional arguments:**
+
+``--subscriber <subscriber>``
+   Subscriber which will be notified.
+
+``--ttl <ttl>``
+  Time to live of the subscription in seconds.
+
+``--options <options>``
+  Metadata of the subscription in JSON format.
+
+