Command docs: add service

Co-Authored-By: Lin Hua Cheng <os.lcheng@gmail.com>

Change-Id: Icd39e6d769fd4c4797fcf4ef9eb97c71ed166b3b
Closes-Bug: #1404434

4 files changed, 170 insertions, 14 deletions

diff --git a/doc/source/command-objects/service.rst b/doc/source/command-objects/service.rst
new file mode 100644
index 00000000..d4f63de8
--- /dev/null
+++ b/doc/source/command-objects/service.rst
@@ -0,0 +1,144 @@
+=======
+service
+=======
+
+Identity v2, v3
+
+service create
+--------------
+
+Create new service
+
+.. program:: service create
+.. code-block:: bash
+
+    os service create
+        [--name <name>]
+        [--description <description>]
+        [--enable | --disable]
+        <type>
+
+.. option:: --name <name>
+
+    New service name
+
+.. option:: --description <description>
+
+    New service description
+
+.. option:: --enable
+
+    Enable service (default)
+
+    *Identity version 3 only*
+
+.. option:: --disable
+
+    Disable service
+
+    *Identity version 3 only*
+
+.. _service_create-type:
+.. describe:: <type>
+
+    New service type (compute, image, identity, volume, etc)
+
+service delete
+--------------
+
+Delete service
+
+.. program:: service delete
+.. code-block:: bash
+
+    os service delete
+        <service>
+
+:option:`<service>`
+    Service to delete (type, name or ID)
+
+service list
+------------
+
+List services
+
+.. program:: service list
+.. code-block:: bash
+
+    os service list
+        [--long]
+
+.. option:: --long
+
+    List additional fields in output
+
+    *Identity version 2 only*
+
+Returns service fields ID and Name, `--long` adds Type and Description
+to the output.  When Identity API version 3 is selected all columns are
+always displayed, `--long` is silently accepted for backward-compatibility.
+
+service set
+-----------
+
+Set service properties
+
+* Identity version 3 only*
+
+.. program:: service set
+.. code-block:: bash
+
+    os service set
+        [--type <type>]
+        [--name <name>]
+        [--description <description>]
+        [--enable | --disable]
+        <service>
+
+.. option:: --type <type>
+
+    New service type (compute, image, identity, volume, etc)
+
+.. option:: --name <name>
+
+    New service name
+
+.. option:: --description <description>
+
+    New service description
+
+.. option:: --enable
+
+    Enable service
+
+.. option:: --disable
+
+    Disable service
+
+.. _service_set-service:
+.. describe:: <service>
+
+    Service to update (type, name or ID)
+
+service show
+------------
+
+Display service details
+
+.. program:: service show
+.. code-block:: bash
+
+    os service show
+        [--catalog]
+        <service>
+
+.. option:: --catalog
+
+    Show service catalog information
+
+    *Identity version 2 only*
+
+.. _service_show-service:
+.. describe:: <service>
+
+    Service to display (type, name or ID)
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 3a7fdd23..6fe91a1f 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -109,7 +109,7 @@ referring to both Compute and Volume quotas.
 * ``security group rule``: Compute, Network - the individual rules that define protocol/IP/port access
 * ``server``: (**Compute**) virtual machine instance
 * ``server image``: (**Compute**) saved server disk image
-* ``service``: Identity - a cloud service
+* ``service``: (**Identity**) a cloud service
 * ``snapshot``: (**Volume**) a point-in-time copy of a volume
 * ``token``: (**Identity**) a bearer token managed by Identity service
 * ``usage``: (**Compute**) display host resources being consumed
diff --git a/openstackclient/identity/v2_0/service.py b/openstackclient/identity/v2_0/service.py
index 0b98a903..208f7fbc 100644
--- a/openstackclient/identity/v2_0/service.py
+++ b/openstackclient/identity/v2_0/service.py
@@ -44,7 +44,7 @@ class CreateService(show.ShowOne):
         type_or_name_group = parser.add_mutually_exclusive_group()
         type_or_name_group.add_argument(
             '--type',
-            metavar='<service-type>',
+            metavar='<type>',
             help=argparse.SUPPRESS,
         )
         type_or_name_group.add_argument(
@@ -54,7 +54,7 @@ class CreateService(show.ShowOne):
         )
         parser.add_argument(
             '--description',
-            metavar='<service-description>',
+            metavar='<description>',
             help=_('New service description'),
         )
         return parser
@@ -144,7 +144,7 @@ class ListService(lister.Lister):
 
 
 class ShowService(show.ShowOne):
-    """Show service details"""
+    """Display service details"""
 
     log = logging.getLogger(__name__ + '.ShowService')
 
diff --git a/openstackclient/identity/v3/service.py b/openstackclient/identity/v3/service.py
index f4c5d426..12629253 100644
--- a/openstackclient/identity/v3/service.py
+++ b/openstackclient/identity/v3/service.py
@@ -15,6 +15,7 @@
 
 """Identity v3 Service action implementations"""
 
+import argparse
 import logging
 import six
 
@@ -35,12 +36,12 @@ class CreateService(show.ShowOne):
         parser = super(CreateService, self).get_parser(prog_name)
         parser.add_argument(
             'type',
-            metavar='<service-type>',
+            metavar='<type>',
             help='New service type (compute, image, identity, volume, etc)',
         )
         parser.add_argument(
             '--name',
-            metavar='<service-name>',
+            metavar='<name>',
             help='New service name',
         )
         parser.add_argument(
@@ -52,12 +53,12 @@ class CreateService(show.ShowOne):
         enable_group.add_argument(
             '--enable',
             action='store_true',
-            help='Enable project',
+            help='Enable service (default)',
         )
         enable_group.add_argument(
             '--disable',
             action='store_true',
-            help='Disable project',
+            help='Disable service',
         )
         return parser
 
@@ -90,7 +91,7 @@ class DeleteService(command.Command):
         parser.add_argument(
             'service',
             metavar='<service>',
-            help='Service to delete (name or ID)',
+            help='Service to delete (type or ID)',
         )
         return parser
 
@@ -109,6 +110,17 @@ class ListService(lister.Lister):
 
     log = logging.getLogger(__name__ + '.ListService')
 
+    def get_parser(self, prog_name):
+        """The --long option is here for compatibility only."""
+        parser = super(ListService, self).get_parser(prog_name)
+        parser.add_argument(
+            '--long',
+            action='store_true',
+            default=False,
+            help=argparse.SUPPRESS,
+        )
+        return parser
+
     def take_action(self, parsed_args):
         self.log.debug('take_action(%s)', parsed_args)
 
@@ -131,11 +143,11 @@ class SetService(command.Command):
         parser.add_argument(
             'service',
             metavar='<service>',
-            help='Service to update (name or ID)',
+            help='Service to update (type, name or ID)',
         )
         parser.add_argument(
             '--type',
-            metavar='<service-type>',
+            metavar='<type>',
             help='New service type (compute, image, identity, volume, etc)',
         )
         parser.add_argument(
@@ -152,12 +164,12 @@ class SetService(command.Command):
         enable_group.add_argument(
             '--enable',
             action='store_true',
-            help='Enable project',
+            help='Enable service',
         )
         enable_group.add_argument(
             '--disable',
             action='store_true',
-            help='Disable project',
+            help='Disable service',
         )
         return parser
 
@@ -194,7 +206,7 @@ class SetService(command.Command):
 
 
 class ShowService(show.ShowOne):
-    """Show service details"""
+    """Display service details"""
 
     log = logging.getLogger(__name__ + '.ShowService')