Improve help strings

Make help strings more consistent:
* Fix spelling and capitalization
* Add "." at end of each string
* Fix spaces.
* Improve wording

Change-Id: I22e84ebecb87f1c803cfb8369db3798fe56903ff

README.rst

@@ -75,25 +75,48 @@ You'll find complete documentation on the shell by running
        <subcommand>
          backup-create       Creates a backup.
          backup-delete       Deletes a backup.
-         backup-list         List available backups.
+         backup-list         Lists available backups.
          backup-list-instance
-                             List available backups for an instance.
+                             Lists available backups for an instance.
-         backup-show         Show details of a backup.
+         backup-show         Shows details of a backup.
+         configuration-attach
+                             Attaches a configuration group to an instance.
+         configuration-create
+                             Creates a configuration group.
+         configuration-default
+                             Shows the default configuration of an instance.
+         configuration-delete
+                             Deletes a configuration group.
+         configuration-detach
+                             Detaches a configuration group from an instance.
+         configuration-instances
+                             Lists all instances associated with a configuration
+                             group.
+         configuration-list  Lists all configuration groups.
+         configuration-parameter-list
+                             Lists available parameters for a configuration group.
+         configuration-parameter-show
+                             Shows details of a configuration parameter.
+         configuration-patch
+                             Patches a configuration group.
+         configuration-show  Shows details of a configuration group.
+         configuration-update
+                             Updates a configuration group.
          create              Creates a new instance.
          database-create     Creates a database on an instance.
          database-delete     Deletes a database.
          database-list       Lists available databases on an instance.
-         datastore-list      List all the datastores.
+         datastore-list      Lists available datastores.
-         datastore-show      Show details of a datastore.
+         datastore-show      Shows details of a datastore.
          datastore-version-list
-                             List all the datastore versions.
+                             Lists available versions for a datastore.
          datastore-version-show
-                             Show details of a datastore version.
+                             Shows details of a datastore version.
          delete              Deletes an instance.
          flavor-list         Lists available flavors.
-         flavor-show         Show details of a flavor.
+         flavor-show         Shows details of a flavor.
          limit-list          Lists the limits for a tenant.
-         list                List all the instances.
+         list                Lists all the instances.
          resize-flavor       Resizes the flavor of an instance.
          resize-volume       Resizes the volume size of an instance.
          restart             Restarts the instance.
@@ -104,7 +127,7 @@ You'll find complete documentation on the shell by running
                              Deletes a security group rule.
          secgroup-list       Lists all security groups.
          secgroup-show       Shows details about a security group.
-         show                Show details of an instance.
+         show                Shows details of an instance.
          user-create         Creates a user.
          user-delete         Deletes a user from the instance.
          user-grant-access   Grants access to a database(s) for a user.
@@ -114,13 +137,13 @@ You'll find complete documentation on the shell by running
          user-show-access    Gets a users access from the instance.
          user-update-attributes
                              Updates a users attributes from the instance.
-         bash-completion     Print arguments for bash_completion.
+         bash-completion     Prints arguments for bash_completion.
-         help                Display help about this program or one of its
+         help                Displays help about this program or one of its
                              subcommands.
 
      Optional arguments:
        --version             show program's version number and exit
-       --debug               Print debugging output
+       --debug               Print debugging output.
        --os-username <auth-user-name>
                              Defaults to env[OS_USERNAME].
        --os-password <auth-password>
@@ -134,24 +157,25 @@ You'll find complete documentation on the shell by running
        --os-region-name <region-name>
                              Defaults to env[OS_REGION_NAME].
        --service-type <service-type>
-                             Defaults to database for most actions
+                             Defaults to database for most actions.
        --service-name <service-name>
-                             Defaults to env[TROVE_SERVICE_NAME]
+                             Defaults to env[TROVE_SERVICE_NAME].
        --bypass-url <bypass-url>
-                             Defaults to env[TROVE_BYPASS_URL]
+                             Defaults to env[TROVE_BYPASS_URL].
        --database-service-name <database-service-name>
-                             Defaults to env[TROVE_DATABASE_SERVICE_NAME]
+                             Defaults to env[TROVE_DATABASE_SERVICE_NAME].
        --endpoint-type <endpoint-type>
                              Defaults to env[TROVE_ENDPOINT_TYPE] or publicURL.
        --os-database-api-version <database-api-ver>
-                             Accepts 1,defaults to env[OS_DATABASE_API_VERSION].
+                             Accepts 1, defaults to env[OS_DATABASE_API_VERSION].
        --os-cacert <ca-certificate>
                              Specify a CA bundle file to use in verifying a TLS
-                             (https) server certificate. Defaults to env[OS_CACERT]
+                             (https) server certificate. Defaults to
+                             env[OS_CACERT].
        --retries <retries>   Number of retries.
        --json, --os-json-output
                              Output json instead of prettyprint. Defaults to
-                             OS_JSON_OUTPUT
+                             env[OS_JSON_OUTPUT].
 
 Python API
 ----------

troveclient/compat/common.py

@@ -159,21 +159,21 @@ class CliOptions(object):
                    help="Show the stack trace on errors.")
         add_option("auth_url", help="Auth API endpoint URL with port and "
                    "version. Default: http://localhost:5000/v2.0")
-        add_option("username", help="Login username")
+        add_option("username", help="Login username.")
-        add_option("apikey", help="Api key")
+        add_option("apikey", help="API key.")
         add_option("tenant_id",
-                   help="Tenant Id associated with the account")
+                   help="Tenant Id associated with the account.")
         add_option("auth_type",
                    help="Auth type to support different auth environments, \
                                 Supported values are 'keystone', 'rax'.")
         add_option("service_type",
-                   help="Service type is a name associated for the catalog")
+                   help="Service type is a name associated for the catalog.")
         add_option("service_name",
-                   help="Service name as provided in the service catalog")
+                   help="Service name as provided in the service catalog.")
         add_option("service_url",
                    help="Service endpoint to use "
                         "if the catalog doesn't have one.")
-        add_option("region", help="Region the service is located in")
+        add_option("region", help="Region the service is located in.")
         add_option("insecure", action="store_true",
                    help="Run in insecure mode for https endpoints.")
         add_option("token", help="Token from a prior login.")

troveclient/shell.py

@@ -95,7 +95,7 @@ class OpenStackTroveShell(object):
                             action='store_true',
                             default=utils.env('TROVECLIENT_DEBUG',
                                               default=False),
-                            help="Print debugging output")
+                            help="Print debugging output.")
 
         parser.add_argument('--os-username',
                             metavar='<auth-user-name>',
@@ -149,21 +149,21 @@ class OpenStackTroveShell(object):
                             metavar='<service-type>',
                             default=utils.env('OS_SERVICE_TYPE',
                                               'TROVE_SERVICE_TYPE'),
-                            help='Defaults to database for most actions')
+                            help='Defaults to database for most actions.')
         parser.add_argument('--service_type',
                             help=argparse.SUPPRESS)
 
         parser.add_argument('--service-name',
                             metavar='<service-name>',
                             default=utils.env('TROVE_SERVICE_NAME'),
-                            help='Defaults to env[TROVE_SERVICE_NAME]')
+                            help='Defaults to env[TROVE_SERVICE_NAME].')
         parser.add_argument('--service_name',
                             help=argparse.SUPPRESS)
 
         parser.add_argument('--bypass-url',
                             metavar='<bypass-url>',
                             default=utils.env('TROVE_BYPASS_URL'),
-                            help='Defaults to env[TROVE_BYPASS_URL]')
+                            help='Defaults to env[TROVE_BYPASS_URL].')
         parser.add_argument('--bypass_url',
                             help=argparse.SUPPRESS)
 
@@ -171,7 +171,7 @@ class OpenStackTroveShell(object):
                             metavar='<database-service-name>',
                             default=utils.env('TROVE_DATABASE_SERVICE_NAME'),
                             help='Defaults to env'
-                            '[TROVE_DATABASE_SERVICE_NAME]')
+                            '[TROVE_DATABASE_SERVICE_NAME].')
         parser.add_argument('--database_service_name',
                             help=argparse.SUPPRESS)
 
@@ -190,7 +190,7 @@ class OpenStackTroveShell(object):
                             default=utils.env(
                                 'OS_DATABASE_API_VERSION',
                                 default=DEFAULT_OS_DATABASE_API_VERSION),
-                            help='Accepts 1,defaults '
+                            help='Accepts 1, defaults '
                                  'to env[OS_DATABASE_API_VERSION].')
         parser.add_argument('--os_database_api_version',
                             help=argparse.SUPPRESS)
@@ -200,7 +200,7 @@ class OpenStackTroveShell(object):
                             default=utils.env('OS_CACERT', default=None),
                             help='Specify a CA bundle file to use in '
                             'verifying a TLS (https) server certificate. '
-                            'Defaults to env[OS_CACERT]')
+                            'Defaults to env[OS_CACERT].')
 
         parser.add_argument('--insecure',
                             default=utils.env('TROVECLIENT_INSECURE',
@@ -220,7 +220,7 @@ class OpenStackTroveShell(object):
                             default=utils.env('OS_JSON_OUTPUT',
                                               default=False),
                             help='Output json instead of prettyprint. '
-                                 'Defaults to OS_JSON_OUTPUT')
+                                 'Defaults to env[OS_JSON_OUTPUT].')
 
         # FIXME(dtroyer): The args below are here for diablo compatibility,
         #                 remove them in folsum cycle
@@ -511,7 +511,7 @@ class OpenStackTroveShell(object):
             extension.run_hooks(hook_type, *args, **kwargs)
 
     def do_bash_completion(self, args):
-        """Print arguments for bash_completion.
+        """Prints arguments for bash_completion.
 
         Prints all of the commands and options to stdout so that the
         trove.bash_completion script doesn't have to hard code them.
@@ -528,10 +528,10 @@ class OpenStackTroveShell(object):
         print(' '.join(commands | options))
 
     @utils.arg('command', metavar='<subcommand>', nargs='?',
-               help='Display help for <subcommand>')
+               help='Display help for <subcommand>.')
     def do_help(self, args):
         """
-        Display help about this program or one of its subcommands.
+        Displays help about this program or one of its subcommands.
         """
         if args.command:
             if args.command in self.subcommands:

troveclient/v1/shell.py

@@ -89,7 +89,7 @@ def do_flavor_list(cs, args):
 @utils.arg('flavor', metavar='<flavor>', help='ID of the flavor.')
 @utils.service_type('database')
 def do_flavor_show(cs, args):
-    """Show details of a flavor."""
+    """Shows details of a flavor."""
     flavor = _find_flavor(cs, args.flavor)
     _print_instance(flavor)
 
@@ -98,7 +98,7 @@ def do_flavor_show(cs, args):
 
 @utils.service_type('database')
 def do_list(cs, args):
-    """List all the instances."""
+    """Lists all the instances."""
     instances = cs.instances.list()
 
     for instance in instances:
@@ -118,7 +118,7 @@ def do_list(cs, args):
 @utils.arg('instance', metavar='<instance>', help='ID of the instance.')
 @utils.service_type('database')
 def do_show(cs, args):
-    """Show details of an instance."""
+    """Shows details of an instance."""
     instance = _find_instance(cs, args.instance)
     instance._info['flavor'] = instance.flavor['id']
     if hasattr(instance, 'volume'):
@@ -145,15 +145,15 @@ def do_delete(cs, args):
 @utils.arg('name',
            metavar='<name>',
            type=str,
-           help='Name of the instance')
+           help='Name of the instance.')
 @utils.arg('--size',
            metavar='<size>',
            type=int,
            default=None,
-           help='Size of the instance disk in GB')
+           help='Size of the instance disk in GB.')
 @utils.arg('flavor_id',
            metavar='<flavor_id>',
-           help='Flavor of the instance')
+           help='Flavor of the instance.')
 @utils.arg('--databases', metavar='<databases>',
            help='Optional list of databases.',
            nargs="+", default=[])
@@ -163,19 +163,19 @@ def do_delete(cs, args):
 @utils.arg('--backup',
            metavar='<backup>',
            default=None,
-           help='A backup UUID')
+           help='A backup UUID.')
 @utils.arg('--availability_zone',
            metavar='<availability_zone>',
            default=None,
-           help='The Zone hint to give to nova')
+           help='The Zone hint to give to nova.')
 @utils.arg('--datastore',
            metavar='<datastore>',
            default=None,
-           help='A datastore name or UUID')
+           help='A datastore name or UUID.')
 @utils.arg('--datastore_version',
            metavar='<datastore_version>',
            default=None,
-           help='A datastore version name or UUID')
+           help='A datastore version name or UUID.')
 @utils.arg('--nic',
            metavar="<net-id=net-uuid,v4-fixed-ip=ip-addr,port-id=port-uuid>",
            action='append',
@@ -184,14 +184,14 @@ def do_delete(cs, args):
            help="Create a NIC on the instance. "
                 "Specify option multiple times to create multiple NICs. "
                 "net-id: attach NIC to network with this UUID "
-                "(required if no port-id), "
+                "(required, if no port-id specified), "
                 "v4-fixed-ip: IPv4 fixed address for NIC (optional), "
                 "port-id: attach NIC to port with this UUID "
-                "(required if no net-id)")
+                "(required, if no net-id specified).")
 @utils.arg('--configuration',
            metavar='<configuration>',
            default=None,
-           help='UUID of the configuration group to attach to the instance')
+           help='UUID of the configuration group to attach to the instance.')
 @utils.service_type('database')
 def do_create(cs, args):
     """Creates a new instance."""
@@ -241,10 +241,10 @@ def do_create(cs, args):
 @utils.arg('instance',
            metavar='<instance>',
            type=str,
-           help='UUID of the instance')
+           help='UUID of the instance.')
 @utils.arg('flavor_id',
            metavar='<flavor_id>',
-           help='Flavor of the instance')
+           help='Flavor of the instance.')
 @utils.service_type('database')
 def do_resize_flavor(cs, args):
     """Resizes the flavor of an instance."""
@@ -254,12 +254,12 @@ def do_resize_flavor(cs, args):
 @utils.arg('instance',
            metavar='<instance>',
            type=str,
-           help='UUID of the instance')
+           help='UUID of the instance.')
 @utils.arg('size',
            metavar='<size>',
            type=int,
            default=None,
-           help='Size of the instance disk in GB')
+           help='Size of the instance disk in GB.')
 @utils.service_type('database')
 def do_resize_volume(cs, args):
     """Resizes the volume size of an instance."""
@@ -269,7 +269,7 @@ def do_resize_volume(cs, args):
 @utils.arg('instance',
            metavar='<instance>',
            type=str,
-           help='UUID of the instance')
+           help='UUID of the instance.')
 @utils.service_type('database')
 def do_restart(cs, args):
     """Restarts the instance."""
@@ -281,7 +281,7 @@ def do_restart(cs, args):
 @utils.arg('backup', metavar='<backup>', help='ID of the backup.')
 @utils.service_type('database')
 def do_backup_show(cs, args):
-    """Show details of a backup."""
+    """Shows details of a backup."""
     backup = _find_backup(cs, args.backup)
     _print_instance(backup)
 
@@ -292,7 +292,7 @@ def do_backup_show(cs, args):
 @utils.arg('instance', metavar='<instance>', help='ID of the instance.')
 @utils.service_type('database')
 def do_backup_list_instance(cs, args):
-    """List available backups for an instance."""
+    """Lists available backups for an instance."""
     wrapper = cs.instances.backups(args.instance, limit=args.limit)
     backups = wrapper.items
     while wrapper.next and not args.limit:
@@ -308,7 +308,7 @@ def do_backup_list_instance(cs, args):
            help='Return up to N number of the most recent backups.')
 @utils.service_type('database')
 def do_backup_list(cs, args):
-    """List available backups."""
+    """Lists available backups."""
     wrapper = cs.backups.list(limit=args.limit)
     backups = wrapper.items
     while wrapper.next and not args.limit:
@@ -349,9 +349,9 @@ def do_backup_create(cs, args):
 @utils.arg('name', metavar='<name>', help='Name of the database.')
 @utils.arg('--character_set', metavar='<character_set>',
            default=None,
-           help='Optional character set for database')
+           help='Optional character set for database.')
 @utils.arg('--collate', metavar='<collate>', default=None,
-           help='Optional collation type for database')
+           help='Optional collation type for database.')
 @utils.service_type('database')
 def do_database_create(cs, args):
     """Creates a database on an instance."""
@@ -388,10 +388,10 @@ def do_database_delete(cs, args):
 # User related actions
 
 @utils.arg('instance', metavar='<instance>', help='UUID of the instance.')
-@utils.arg('name', metavar='<name>', help='Name of user')
+@utils.arg('name', metavar='<name>', help='Name of user.')
-@utils.arg('password', metavar='<password>', help='Password of user')
+@utils.arg('password', metavar='<password>', help='Password of user.')
 @utils.arg('--host', metavar='<host>', default=None,
-           help='Optional host of user')
+           help='Optional host of user.')
 @utils.arg('--databases', metavar='<databases>',
            help='Optional list of databases.',
            nargs="+", default=[])
@@ -422,9 +422,9 @@ def do_user_list(cs, args):
 
 
 @utils.arg('instance', metavar='<instance>', help='UUID of the instance.')
-@utils.arg('name', metavar='<name>', help='Name of user')
+@utils.arg('name', metavar='<name>', help='Name of user.')
 @utils.arg('--host', metavar='<host>', default=None,
-           help='Optional host of user')
+           help='Optional host of user.')
 @utils.service_type('database')
 def do_user_delete(cs, args):
     """Deletes a user from the instance."""
@@ -432,9 +432,9 @@ def do_user_delete(cs, args):
 
 
 @utils.arg('instance', metavar='<instance>', help='UUID of the instance.')
-@utils.arg('name', metavar='<name>', help='Name of user')
+@utils.arg('name', metavar='<name>', help='Name of user.')
 @utils.arg('--host', metavar='<host>', default=None,
-           help='Optional host of user')
+           help='Optional host of user.')
 @utils.service_type('database')
 # Quoting is not working now that we aren't using httplib2
 # anymore and instead are using requests
@@ -445,9 +445,9 @@ def do_user_show(cs, args):
 
 
 @utils.arg('instance', metavar='<instance>', help='UUID of the instance.')
-@utils.arg('name', metavar='<name>', help='Name of user')
+@utils.arg('name', metavar='<name>', help='Name of user.')
 @utils.arg('--host', metavar='<host>', default=None,
-           help='Optional host of user')
+           help='Optional host of user.')
 @utils.service_type('database')
 # Quoting is not working now that we aren't using httplib2
 # anymore and instead are using requests
@@ -458,15 +458,15 @@ def do_user_show_access(cs, args):
 
 
 @utils.arg('instance', metavar='<instance>', help='UUID of the instance.')
-@utils.arg('name', metavar='<name>', help='Name of user')
+@utils.arg('name', metavar='<name>', help='Name of user.')
 @utils.arg('--host', metavar='<host>', default=None,
-           help='Optional host of user')
+           help='Optional host of user.')
 @utils.arg('--new_name', metavar='<new_name>', default=None,
-           help='Optional new name of user')
+           help='Optional new name of user.')
 @utils.arg('--new_password', metavar='<new_password>', default=None,
-           help='Optional new password of user')
+           help='Optional new password of user.')
 @utils.arg('--new_host', metavar='<new_host>', default=None,
-           help='Optional new host of user')
+           help='Optional new host of user.')
 @utils.service_type('database')
 # Quoting is not working now that we aren't using httplib2
 # anymore and instead are using requests
@@ -484,9 +484,9 @@ def do_user_update_attributes(cs, args):
 
 
 @utils.arg('instance', metavar='<instance>', help='UUID of the instance.')
-@utils.arg('name', metavar='<name>', help='Name of user')
+@utils.arg('name', metavar='<name>', help='Name of user.')
 @utils.arg('--host', metavar='<host>', default=None,
-           help='Optional host of user')
+           help='Optional host of user.')
 @utils.arg('databases', metavar='<databases>',
            help='List of databases.',
            nargs="+", default=[])
@@ -498,13 +498,13 @@ def do_user_grant_access(cs, args):
 
 
 @utils.arg('instance', metavar='<instance>', help='UUID of the instance.')
-@utils.arg('name', metavar='<name>', help='Name of user')
+@utils.arg('name', metavar='<name>', help='Name of user.')
 @utils.arg('database', metavar='<database>', help='A single database.')
 @utils.arg('--host', metavar='<host>', default=None,
-           help='Optional host of user')
+           help='Optional host of user.')
 @utils.service_type('database')
 def do_user_revoke_access(cs, args):
-    """Revokes access to a database for a  user."""
+    """Revokes access to a database for a user."""
     cs.users.revoke(args.instance, args.name,
                     args.database, hostname=args.host)
 
@@ -563,11 +563,13 @@ def do_secgroup_show(cs, args):
 
 
 @utils.arg('security_group', metavar='<security_group>',
-           help='Security group name')
+           help='Security group name.')
-@utils.arg('protocol', metavar='<protocol>', help='Protocol')
+@utils.arg('protocol', metavar='<protocol>',
-@utils.arg('from_port', metavar='<from_port>', help='from port')
+           help='IP protocol (icmp, tcp, udp).')
-@utils.arg('to_port', metavar='<to_port>', help='to port')
+@utils.arg('from_port', metavar='<from_port>',
-@utils.arg('cidr', metavar='<cidr>', help='CIDR address')
+           help='Port at start of range.')
+@utils.arg('to_port', metavar='<to_port>', help='Port at end of range.')
+@utils.arg('cidr', metavar='<cidr>', help='CIDR address.')
 @utils.service_type('database')
 def do_secgroup_add_rule(cs, args):
     """Creates a security group rule."""
@@ -581,7 +583,7 @@ def do_secgroup_add_rule(cs, args):
 
 
 @utils.arg('security_group_rule', metavar='<security_group_rule>',
-           help='Security group rule')
+           help='Name of security group rule.')
 @utils.service_type('database')
 def do_secgroup_delete_rule(cs, args):
     """Deletes a security group rule."""
@@ -590,7 +592,7 @@ def do_secgroup_delete_rule(cs, args):
 
 @utils.service_type('database')
 def do_datastore_list(cs, args):
-    """List available datastores."""
+    """Lists available datastores."""
     datastores = cs.datastores.list()
     utils.print_list(datastores, ['id', 'name'])
 
@@ -599,7 +601,7 @@ def do_datastore_list(cs, args):
            help='ID of the datastore.')
 @utils.service_type('database')
 def do_datastore_show(cs, args):
-    """Show details of a datastore."""
+    """Shows details of a datastore."""
     datastore = cs.datastores.get(args.datastore)
     if hasattr(datastore, 'default_version'):
         datastore._info['default_version'] = getattr(datastore,
@@ -611,7 +613,7 @@ def do_datastore_show(cs, args):
            help='ID of the datastore.')
 @utils.service_type('database')
 def do_datastore_version_list(cs, args):
-    """List available versions for a datastore."""
+    """Lists available versions for a datastore."""
     datastore_versions = cs.datastore_versions.list(args.datastore)
     utils.print_list(datastore_versions, ['id', 'name'])
 
@@ -624,7 +626,7 @@ def do_datastore_version_list(cs, args):
            help='ID of the datastore version.')
 @utils.service_type('database')
 def do_datastore_version_show(cs, args):
-    """Show details of a datastore version."""
+    """Shows details of a datastore version."""
     if args.datastore:
         datastore_version = cs.datastore_versions.get(args.datastore,
                                                       args.datastore_version)
@@ -643,11 +645,11 @@ def do_datastore_version_show(cs, args):
 @utils.arg('configuration',
            metavar='<configuration>',
            type=str,
-           help='UUID of the configuration group to attach to the instance')
+           help='UUID of the configuration group to attach to the instance.')
 @utils.arg('instance',
            metavar='<instance>',
            type=str,
-           help='UUID of the instance')
+           help='UUID of the instance.')
 @utils.service_type('database')
 def do_configuration_attach(cs, args):
     """Attaches a configuration group to an instance."""
@@ -679,7 +681,7 @@ def do_configuration_create(cs, args):
 @utils.arg('instance',
            metavar='<instance>',
            type=str,
-           help='UUID of the instance')
+           help='UUID of the instance.')
 @utils.service_type('database')
 def do_configuration_default(cs, args):
     """Shows the default configuration of an instance."""
@@ -698,7 +700,7 @@ def do_configuration_delete(cs, args):
 @utils.arg('instance',
            metavar='<instance>',
            type=str,
-           help='UUID of the instance')
+           help='UUID of the instance.')
 @utils.service_type('database')
 def do_configuration_detach(cs, args):
     """Detaches a configuration group from an instance."""