Command docs: region

Fix up formatting fro region command docs and help

Change-Id: Icf8c03da38b30fc69e7fe70f9c14aaa99881d320

3 files changed, 64 insertions, 44 deletions

diff --git a/doc/source/command-objects/region.rst b/doc/source/command-objects/region.rst
index 788ed6fa..d1aedb31 100644
--- a/doc/source/command-objects/region.rst
+++ b/doc/source/command-objects/region.rst
@@ -9,24 +9,30 @@ region create
 
 Create new region
 
+.. program:: region create
 .. code:: bash
 
     os region create
         [--parent-region <region-id>]
-        [--description <region-description>]
-        [--url <region-url>]
+        [--description <description>]
+        [--url <url>]
         <region-id>
 
-:option:`--parent-region` <region-id>
-    Parent region
+.. option:: --parent-region <region-id>
+
+    Parent region ID
+
+.. option:: --description <description>
 
-:option:`--description` <region-description>
     New region description
 
-:option:`--url` <region-url>
+.. option:: --url <url>
+
     New region URL
 
-:option:`<region-id>`
+.. _region_create-region-id:
+.. describe:: <region-id>
+
     New region ID
 
 region delete
@@ -34,61 +40,75 @@ region delete
 
 Delete region
 
+.. program:: region delete
 .. code:: bash
 
     os region delete
-        <region>
+        <region-id>
+
+.. _region_delete-region-id:
+.. describe:: <region-id>
 
-:option:`<region>`
-    Region to delete
+    Region ID to delete
 
 region list
 -----------
 
 List regions
 
+.. program:: region list
 .. code:: bash
 
     os region list
         [--parent-region <region-id>]
 
-:option:`--parent-region` <region-id>
-    Filter by a specific parent region
+.. option:: --parent-region <region-id>
+
+    Filter by parent region ID
 
 region set
 ----------
 
 Set region properties
 
+.. program:: region set
 .. code:: bash
 
     os region set
         [--parent-region <region-id>]
-        [--description <region-description>]
-        [--url <region-url>]
-        <region>
+        [--description <description>]
+        [--url <url>]
+        <region-id>
 
-:option:`--parent-region` <region-id>
-    New parent region
+.. option:: --parent-region <region-id>
+
+    New parent region ID
+
+.. option:: --description <description>
 
-:option:`--description` <region-description>
     New region description
 
-:option:`--url` <region-url>
+.. option:: --url <url>
+
     New region URL
 
-:option:`<region>`
+.. _region_set-region-id:
+.. describe:: <region-id>
+
     Region ID to modify
 
 region show
 -----------
 
-Show region
+Display region details
 
+.. program:: region show
 .. code:: bash
 
     os region show
-    <region>
+        <region-id>
 
-:option:`<region>`
-    Region ID to modify
+.. _region_show-region-id:
+.. describe:: <region-id>
+
+    Region ID to display
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 04c451c8..6aaa25e7 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -97,7 +97,7 @@ referring to both Compute and Volume quotas.
 * ``policy``: Identity - determines authorization
 * ``project``: (**Identity**) owns a group of resources
 * ``quota``: (**Compute**, **Volume**) resource usage restrictions
-* ``region``: (**Identity**)
+* ``region``: (**Identity**) a subset of an OpenStack deployment
 * ``request token``: Identity - temporary OAuth-based token
 * ``role``: Identity - a policy object used to determine authorization
 * ``security group``: Compute, Network - groups of network access rules
diff --git a/openstackclient/identity/v3/region.py b/openstackclient/identity/v3/region.py
index cce3417d..5fb73913 100644
--- a/openstackclient/identity/v3/region.py
+++ b/openstackclient/identity/v3/region.py
@@ -35,22 +35,22 @@ class CreateRegion(show.ShowOne):
         # seems like poor UX, we will only support user-defined IDs.
         parser.add_argument(
             'region',
-            metavar='<region>',
-            help=_('New region'),
+            metavar='<region-id>',
+            help=_('New region ID'),
         )
         parser.add_argument(
             '--parent-region',
-            metavar='<parent-region>',
-            help=_('The parent region of new region'),
+            metavar='<region-id>',
+            help=_('Parent region ID'),
         )
         parser.add_argument(
             '--description',
-            metavar='<region-description>',
+            metavar='<description>',
             help=_('New region description'),
         )
         parser.add_argument(
             '--url',
-            metavar='<region-url>',
+            metavar='<url>',
             help=_('New region url'),
         )
 
@@ -82,8 +82,8 @@ class DeleteRegion(command.Command):
         parser = super(DeleteRegion, self).get_parser(prog_name)
         parser.add_argument(
             'region',
-            metavar='<region>',
-            help=_('Region to delete'),
+            metavar='<region-id>',
+            help=_('Region ID to delete'),
         )
         return parser
 
@@ -104,8 +104,8 @@ class ListRegion(lister.Lister):
         parser = super(ListRegion, self).get_parser(prog_name)
         parser.add_argument(
             '--parent-region',
-            metavar='<parent-region>',
-            help=_('Filter by parent region'),
+            metavar='<region-id>',
+            help=_('Filter by parent region ID'),
         )
         return parser
 
@@ -137,22 +137,22 @@ class SetRegion(command.Command):
         parser = super(SetRegion, self).get_parser(prog_name)
         parser.add_argument(
             'region',
-            metavar='<region>',
-            help=_('Region to change'),
+            metavar='<region-id>',
+            help=_('Region ID to modify'),
         )
         parser.add_argument(
             '--parent-region',
-            metavar='<parent-region>',
-            help=_('New parent region of the region'),
+            metavar='<region-id>',
+            help=_('New parent region ID'),
         )
         parser.add_argument(
             '--description',
-            metavar='<region-description>',
+            metavar='<description>',
             help=_('New region description'),
         )
         parser.add_argument(
             '--url',
-            metavar='<region-url>',
+            metavar='<url>',
             help=_('New region url'),
         )
         return parser
@@ -179,7 +179,7 @@ class SetRegion(command.Command):
 
 
 class ShowRegion(show.ShowOne):
-    """Show region"""
+    """Display region details"""
 
     log = logging.getLogger(__name__ + '.ShowRegion')
 
@@ -187,8 +187,8 @@ class ShowRegion(show.ShowOne):
         parser = super(ShowRegion, self).get_parser(prog_name)
         parser.add_argument(
             'region',
-            metavar='<region>',
-            help=_('Region to display'),
+            metavar='<region-id>',
+            help=_('Region ID to display'),
         )
         return parser