From 59ddb71ce181b669084dc444ee51bfd76b1ae3cf Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Sat, 8 Mar 2014 09:57:29 +0100 Subject: [PATCH] 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 | 64 ++++++++++++++------ troveclient/compat/common.py | 12 ++-- troveclient/shell.py | 22 +++---- troveclient/v1/shell.py | 114 ++++++++++++++++++----------------- 4 files changed, 119 insertions(+), 93 deletions(-) diff --git a/README.rst b/README.rst index be085beb..da879c80 100644 --- a/README.rst +++ b/README.rst @@ -75,25 +75,48 @@ You'll find complete documentation on the shell by running 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. - backup-show Show details of a backup. + Lists available backups for an instance. + 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-show Show details of a datastore. + datastore-list Lists available datastores. + 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. - help Display help about this program or one of its + bash-completion Prints arguments for bash_completion. + 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 Defaults to env[OS_USERNAME]. --os-password @@ -134,24 +157,25 @@ You'll find complete documentation on the shell by running --os-region-name Defaults to env[OS_REGION_NAME]. --service-type - Defaults to database for most actions + Defaults to database for most actions. --service-name - Defaults to env[TROVE_SERVICE_NAME] + Defaults to env[TROVE_SERVICE_NAME]. --bypass-url - Defaults to env[TROVE_BYPASS_URL] + Defaults to env[TROVE_BYPASS_URL]. --database-service-name - Defaults to env[TROVE_DATABASE_SERVICE_NAME] + Defaults to env[TROVE_DATABASE_SERVICE_NAME]. --endpoint-type Defaults to env[TROVE_ENDPOINT_TYPE] or publicURL. --os-database-api-version - Accepts 1,defaults to env[OS_DATABASE_API_VERSION]. + Accepts 1, defaults to env[OS_DATABASE_API_VERSION]. --os-cacert 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 Number of retries. --json, --os-json-output Output json instead of prettyprint. Defaults to - OS_JSON_OUTPUT + env[OS_JSON_OUTPUT]. Python API ---------- diff --git a/troveclient/compat/common.py b/troveclient/compat/common.py index 11853c39..eea7719c 100644 --- a/troveclient/compat/common.py +++ b/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("apikey", help="Api key") + add_option("username", help="Login username.") + 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.") diff --git a/troveclient/shell.py b/troveclient/shell.py index 5cc862aa..899d28cb 100644 --- a/troveclient/shell.py +++ b/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='', @@ -149,21 +149,21 @@ class OpenStackTroveShell(object): metavar='', 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='', 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='', 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='', 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='', nargs='?', - help='Display help for ') + help='Display help for .') 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: diff --git a/troveclient/v1/shell.py b/troveclient/v1/shell.py index 7d877acf..9504471a 100644 --- a/troveclient/v1/shell.py +++ b/troveclient/v1/shell.py @@ -89,7 +89,7 @@ def do_flavor_list(cs, args): @utils.arg('flavor', metavar='', 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='', 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='', type=str, - help='Name of the instance') + help='Name of the instance.') @utils.arg('--size', metavar='', 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='', - help='Flavor of the instance') + help='Flavor of the instance.') @utils.arg('--databases', metavar='', help='Optional list of databases.', nargs="+", default=[]) @@ -163,19 +163,19 @@ def do_delete(cs, args): @utils.arg('--backup', metavar='', default=None, - help='A backup UUID') + help='A backup UUID.') @utils.arg('--availability_zone', metavar='', default=None, - help='The Zone hint to give to nova') + help='The Zone hint to give to nova.') @utils.arg('--datastore', metavar='', default=None, - help='A datastore name or UUID') + help='A datastore name or UUID.') @utils.arg('--datastore_version', metavar='', default=None, - help='A datastore version name or UUID') + help='A datastore version name or UUID.') @utils.arg('--nic', metavar="", 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='', 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='', type=str, - help='UUID of the instance') + help='UUID of the instance.') @utils.arg('flavor_id', metavar='', - 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='', type=str, - help='UUID of the instance') + help='UUID of the instance.') @utils.arg('size', metavar='', 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='', 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='', 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='', 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='', help='Name of the database.') @utils.arg('--character_set', metavar='', default=None, - help='Optional character set for database') + help='Optional character set for database.') @utils.arg('--collate', metavar='', 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='', help='UUID of the instance.') -@utils.arg('name', metavar='', help='Name of user') -@utils.arg('password', metavar='', help='Password of user') +@utils.arg('name', metavar='', help='Name of user.') +@utils.arg('password', metavar='', help='Password of user.') @utils.arg('--host', metavar='', default=None, - help='Optional host of user') + help='Optional host of user.') @utils.arg('--databases', metavar='', help='Optional list of databases.', nargs="+", default=[]) @@ -422,9 +422,9 @@ def do_user_list(cs, args): @utils.arg('instance', metavar='', help='UUID of the instance.') -@utils.arg('name', metavar='', help='Name of user') +@utils.arg('name', metavar='', help='Name of user.') @utils.arg('--host', metavar='', 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='', help='UUID of the instance.') -@utils.arg('name', metavar='', help='Name of user') +@utils.arg('name', metavar='', help='Name of user.') @utils.arg('--host', metavar='', 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='', help='UUID of the instance.') -@utils.arg('name', metavar='', help='Name of user') +@utils.arg('name', metavar='', help='Name of user.') @utils.arg('--host', metavar='', 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='', help='UUID of the instance.') -@utils.arg('name', metavar='', help='Name of user') +@utils.arg('name', metavar='', help='Name of user.') @utils.arg('--host', metavar='', default=None, - help='Optional host of user') + help='Optional host of user.') @utils.arg('--new_name', metavar='', default=None, - help='Optional new name of user') + help='Optional new name of user.') @utils.arg('--new_password', metavar='', default=None, - help='Optional new password of user') + help='Optional new password of user.') @utils.arg('--new_host', metavar='', 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='', help='UUID of the instance.') -@utils.arg('name', metavar='', help='Name of user') +@utils.arg('name', metavar='', help='Name of user.') @utils.arg('--host', metavar='', default=None, - help='Optional host of user') + help='Optional host of user.') @utils.arg('databases', metavar='', help='List of databases.', nargs="+", default=[]) @@ -498,13 +498,13 @@ def do_user_grant_access(cs, args): @utils.arg('instance', metavar='', help='UUID of the instance.') -@utils.arg('name', metavar='', help='Name of user') +@utils.arg('name', metavar='', help='Name of user.') @utils.arg('database', metavar='', help='A single database.') @utils.arg('--host', metavar='', 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='', - help='Security group name') -@utils.arg('protocol', metavar='', help='Protocol') -@utils.arg('from_port', metavar='', help='from port') -@utils.arg('to_port', metavar='', help='to port') -@utils.arg('cidr', metavar='', help='CIDR address') + help='Security group name.') +@utils.arg('protocol', metavar='', + help='IP protocol (icmp, tcp, udp).') +@utils.arg('from_port', metavar='', + help='Port at start of range.') +@utils.arg('to_port', metavar='', help='Port at end of range.') +@utils.arg('cidr', metavar='', 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='', - 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='', 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='', 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='', 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='', 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."""