openstack/python-openstackclient
Code Issues Proposed changes

Help/docs cleanups: marker, limit, ip-address metavars

Browse Source 
Cleanup help strings and docs for clarity and to keep things consistent:
* --limit metavar should be <num-resource> to indicate what is being counted
* --marker metavar should be <resource> or <resource-id> to indicate the
  type of value being specified
* <*-ip-address> metavars should be just <ip-address> as there is no difference
  in format between fixed and floating IPs
* Move all occurances of '(name or ID)' to end of help text

Change-Id: I2c31746ed6ded3845244e03e57d809f8bc0e6b9d
This commit is contained in:
Dean Troyer 2017-04-03 16:15:14 -05:00 committed by Steve Martinelli
parent b2ceb58fc3
commit 1686dc54f0
29 changed files with 121 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/command-objects/container.rst
View File

@ -51,7 +51,7 @@ List containers
[--prefix <prefix>]
[--marker <marker>]
[--end-marker <end-marker>]
[--limit <limit>]
[--limit <num-containers>]
[--long]
[--all]
@ -67,7 +67,7 @@ List containers
End anchor for paging
.. option:: --limit <limit>
.. option:: --limit <num-containers>
Limit the number of containers returned

8
doc/source/command-objects/flavor.rst
View File

@ -108,8 +108,8 @@ List flavors
openstack flavor list
[--public | --private | --all]
[--long]
[--marker <marker>]
[--limit <limit>]
[--marker <flavor-id>]
[--limit <num-flavors>]
.. option:: --public
@ -127,11 +127,11 @@ List flavors
List additional fields in output
.. option:: --marker <marker>
.. option:: --marker <flavor-id>
The last flavor ID of the previous page
.. option:: --limit <limit>
.. option:: --limit <num-flavors>
Maximum number of flavors to display

12
doc/source/command-objects/floating-ip.rst
View File

@ -15,8 +15,8 @@ Create floating IP
openstack floating ip create
[--subnet <subnet>]
[--port <port>]
[--floating-ip-address <floating-ip-address>]
[--fixed-ip-address <fixed-ip-address>]
[--floating-ip-address <ip-address>]
[--fixed-ip-address <ip-address>]
[--description <description>]
[--project <project> [--project-domain <project-domain>]]
<network>
@ -31,12 +31,12 @@ Create floating IP
Port to be associated with the floating IP (name or ID)
*Network version 2 only*
.. option:: --floating-ip-address <floating-ip-address>
.. option:: --floating-ip-address <ip-address>
Floating IP address
*Network version 2 only*
.. option:: --fixed-ip-address <fixed-ip-address>
.. option:: --fixed-ip-address <ip-address>
Fixed IP address mapped to the floating IP
*Network version 2 only*
@ -88,7 +88,7 @@ List floating IP(s)
openstack floating ip list
[--network <network>]
[--port <port>]
[--fixed-ip-address <fixed-ip-address>]
[--fixed-ip-address <ip-address>]
[--long]
[--status <status>]
[--project <project> [--project-domain <project-domain>]]
@ -106,7 +106,7 @@ List floating IP(s)
*Network version 2 only*
.. option:: --fixed-ip-address <fixed-ip-address>
.. option:: --fixed-ip-address <ip-address>
List floating IP(s) according to given fixed IP address

16
doc/source/command-objects/image.rst
View File

@ -199,8 +199,8 @@ List available images
[--property <key=value>]
[--long]
[--sort <key>[:<direction>]]
[--limit <limit>]
[--marker <marker>]
[--limit <num-images>]
[--marker <image>]
.. option:: --public
@ -229,14 +229,18 @@ List available images
Sort output by selected keys and directions(asc or desc) (default: name:asc),
multiple keys and directions can be specified separated by comma
.. option:: --limit <limit>
.. option:: --limit <num-images>
Maximum number of images to display.
.. option:: --marker <marker>
*Image version 2 only*
The last image (name or ID) of the previous page. Display list of images
after marker. Display all images if not specified.
.. option:: --marker <image>
The last image of the previous page. Display list of images
after marker. Display all images if not specified. (name or ID)
*Image version 2 only*
image remove project
--------------------

4
doc/source/command-objects/object.rst
View File

@ -62,7 +62,7 @@ List objects
[--delimiter <delimiter>]
[--marker <marker>]
[--end-marker <end-marker>]
[--limit <limit>]
[--limit <num-objects>]
[--long]
[--all]
<container>
@ -83,7 +83,7 @@ List objects
End anchor for paging
.. option:: --limit <limit>
.. option:: --limit <num-objects>
Limit number of objects returned

10
doc/source/command-objects/port.rst
View File

@ -44,7 +44,7 @@ Create new port
.. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
Desired IP and/or subnet (name or ID) for this port:
Desired IP and/or subnet for this port (name or ID):
subnet=<subnet>,ip-address=<ip-address>
(repeat option to set multiple fixed IP addresses)
@ -182,7 +182,7 @@ List ports
.. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
Desired IP and/or subnet (name or ID) for filtering ports:
Desired IP and/or subnet for filtering ports (name or ID):
subnet=<subnet>,ip-address=<ip-address>
(repeat option to set multiple fixed IP addresses)
@ -234,7 +234,7 @@ Set port properties
.. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
Desired IP and/or subnet (name or ID) for this port:
Desired IP and/or subnet for this port (name or ID):
subnet=<subnet>,ip-address=<ip-address>
(repeat option to set multiple fixed IP addresses)
@ -363,8 +363,8 @@ Unset port properties
.. option:: --fixed-ip subnet=<subnet>,ip-address=<ip-address>
Desired IP and/or subnet (name or ID) which should be removed
from this port: subnet=<subnet>,ip-address=<ip-address>
Desired IP and/or subnet which should be removed
from this port (name or ID): subnet=<subnet>,ip-address=<ip-address>
(repeat option to unset multiple fixed IP addresses)
.. option:: --binding-profile <binding-profile-key>

28
doc/source/command-objects/server.rst
View File

@ -18,11 +18,11 @@ Add fixed IP address to server
.. describe:: <server>
Server (name or ID) to receive the fixed IP address
Server to receive the fixed IP address (name or ID)
.. describe:: <network>
Network (name or ID) to allocate the fixed IP address from
Network to allocate the fixed IP address from (name or ID)
server add floating ip
----------------------
@ -33,21 +33,21 @@ Add floating IP address to server
.. code:: bash
openstack server add floating ip
[--fixed-ip-address <fixed-ip-address>]
[--fixed-ip-address <ip-address>]
<server>
<ip-address>
.. option:: --fixed-ip-address <fixed-ip-address>
.. option:: --fixed-ip-address <ip-address>
Fixed IP address to associate with this floating IP address
.. describe:: <server>
Server (name or ID) to receive the floating IP address
Server to receive the floating IP address (name or ID)
.. describe:: <ip-address>
Floating IP address (IP address only) to assign to server
Floating IP address to assign to server (IP only)
server add security group
-------------------------
@ -264,7 +264,7 @@ List servers
[--project <project> [--project-domain <project-domain>]]
[--long]
[--marker <server>]
[--limit <limit>]
[--limit <num-servers>]
[--deleted]
[--changes-since <changes-since>]
@ -332,10 +332,10 @@ List servers
.. option:: --marker <server>
The last server (name or ID) of the previous page. Display list of servers
after marker. Display all servers if not specified.
The last server of the previous page. Display list of servers
after marker. Display all servers if not specified. (name or ID)
.. option:: --limit <limit>
.. option:: --limit <num-servers>
Maximum number of servers to display. If limit equals -1, all servers will
be displayed. If limit is greater than 'osapi_max_limit' option of Nova
@ -497,11 +497,11 @@ Remove fixed IP address from server
.. describe:: <server>
Server (name or ID) to remove the fixed IP address from
Server to remove the fixed IP address from (name or ID)
.. describe:: <ip-address>
Fixed IP address (IP address only) to remove from the server
Fixed IP address to remove from the server (IP only)
server remove floating ip
-------------------------
@ -517,11 +517,11 @@ Remove floating IP address from server
.. describe:: <server>
Server (name or ID) to remove the floating IP address from
Server to remove the floating IP address from (name or ID)
.. describe:: <ip-address>
Floating IP address (IP address only) to remove from server
Floating IP address to remove from server (IP only)
server remove security group
----------------------------

8
doc/source/command-objects/snapshot.rst
View File

@ -72,8 +72,8 @@ List snapshots
openstack snapshot list
[--all-projects]
[--long]
[--limit <limit>]
[--marker <marker>]
[--limit <num-snapshots>]
[--marker <snapshot>]
.. option:: --all-projects
@ -83,13 +83,13 @@ List snapshots
List additional fields in output
.. option:: --limit <limit>
.. option:: --limit <num-snapshots>
Maximum number of snapshots to display
*Volume version 2 only*
.. option:: --marker <marker>
.. option:: --marker <snapshot>
The last snapshot ID of the previous page

2
doc/source/command-objects/subnet-pool.rst
View File

@ -150,7 +150,7 @@ List subnet pools
.. option:: --address-scope <address-scope>
List only subnet pools of given address scope (name or ID) in output
List only subnet pools of given address scope in output (name or ID)
subnet pool set
---------------

4
doc/source/command-objects/subnet.rst
View File

@ -194,7 +194,7 @@ List subnets
.. option:: --project <project>
List only subnets which belong to a given project (name or ID) in output
List only subnets which belong to a given project in output (name or ID)
.. option:: --project-domain <project-domain>
@ -203,7 +203,7 @@ List subnets
.. option:: --network <network>
List only subnets which belong to a given network (name or ID) in output
List only subnets which belong to a given network in output (name or ID)
.. option:: --gateway <gateway>

8
doc/source/command-objects/volume-backup.rst
View File

@ -92,8 +92,8 @@ List volume backups
[--name <name>]
[--status <status>]
[--volume <volume>]
[--marker <marker>]
[--limit <limit>]
[--marker <volume-backup>]
[--limit <num-backups>]
[--all-projects]
.. _volume_backup_list-backup:
@ -114,13 +114,13 @@ List volume backups
Filters results by the volume which they backup (name or ID)"
.. option:: --marker <marker>
.. option:: --marker <volume-backup>
The last backup of the previous page (name or ID)
*Volume version 2 only*
.. option:: --limit <limit>
.. option:: --limit <num-backups>
Maximum number of backups to display

8
doc/source/command-objects/volume-snapshot.rst
View File

@ -84,8 +84,8 @@ List volume snapshots
[--all-projects]
[--project <project> [--project-domain <project-domain>]]
[--long]
[--limit <limit>]
[--marker <marker>]
[--limit <num-snapshots>]
[--marker <snapshot>]
[--name <name>]
[--status <status>]
[--volume <volume>]
@ -125,13 +125,13 @@ List volume snapshots
Filters results by a volume (name or ID).
.. option:: --limit <limit>
.. option:: --limit <num-snapshots>
Maximum number of snapshots to display
*Volume version 2 only*
.. option:: --marker <marker>
.. option:: --marker <snapshot>
The last snapshot ID of the previous page

8
doc/source/command-objects/volume.rst
View File

@ -158,8 +158,8 @@ List volumes
[--status <status>]
[--all-projects]
[--long]
[--limit <limit>]
[--marker <marker>]
[--limit <num-volumes>]
[--marker <volume>]
.. option:: --project <project>
@ -205,11 +205,11 @@ List volumes
List additional fields in output
.. option:: --limit <limit>
.. option:: --limit <num-volumes>
Maximum number of volumes to display
.. option:: --marker <marker>
.. option:: --marker <volume>
The last volume ID of the previous page

12
doc/source/command-options.rst
View File

@ -283,11 +283,11 @@ There are many ways to do pagination, some OpenStack APIs support it, some
don't. OpenStackClient attempts to define a single common way to specify
pagination on the command line.
.. option:: --marker <marker>
.. option:: --marker <resource>
Anchor for paging
Anchor for paging (name or ID)
.. option:: --limit <limit>
.. option:: --limit <num-resources>
Limit number of <resource> returned (*integer*)
@ -300,13 +300,13 @@ The parser declaration should look like this:
parser.add_argument(
"--marker",
metavar="<marker>",
help="Anchor for paging",
metavar="<resource>",
help="Anchor for paging (name or ID)",
)
parser.add_argument(
"--limit",
metavar="<limit>",
metavar="<num-resources>",
type=int,
help="Limit the number of <resource> returned",
)

4
openstackclient/compute/v2/flavor.py
View File

@ -251,13 +251,13 @@ class ListFlavor(command.Lister):
)
parser.add_argument(
'--marker',
metavar="<marker>",
metavar="<flavor-id>",
help=_("The last flavor ID of the previous page")
)
parser.add_argument(
'--limit',
type=int,
metavar="<limit>",
metavar="<num-flavors>",
help=_("Maximum number of flavors to display")
)
return parser

45
openstackclient/compute/v2/server.py
View File

@ -197,13 +197,14 @@ class AddFixedIP(command.Command):
parser.add_argument(
"server",
metavar="<server>",
help=_("Server (name or ID) to receive the fixed IP address"),
help=_("Server to receive the fixed IP address (name or ID)"),
)
parser.add_argument(
"network",
metavar="<network>",
help=_("Network (name or ID) to allocate "
"the fixed IP address from"),
help=_(
"Network to allocate the fixed IP address from (name or ID)"
),
)
return parser
@ -227,17 +228,16 @@ class AddFloatingIP(command.Command):
parser.add_argument(
"server",
metavar="<server>",
help=_("Server (name or ID) to receive the floating IP address"),
help=_("Server to receive the floating IP address (name or ID)"),
)
parser.add_argument(
"ip_address",
metavar="<ip-address>",
help=_("Floating IP address (IP address only) to assign "
"to server"),
help=_("Floating IP address to assign to server (IP only)"),
)
parser.add_argument(
"--fixed-ip-address",
metavar="<fixed-ip-address>",
metavar="<ip-address>",
help=_("Fixed IP address to associate with this floating IP "
"address"),
)
@ -820,21 +820,21 @@ class ListServer(command.Lister):
)
parser.add_argument(
'--marker',
metavar='<marker>',
metavar='<server>',
default=None,
help=_('The last server (name or ID) of the previous page. Display'
' list of servers after marker. Display all servers if not'
' specified.')
help=_('The last server of the previous page. Display '
'list of servers after marker. Display all servers if not '
'specified. (name or ID)')
)
parser.add_argument(
'--limit',
metavar='<limit>',
metavar='<num-servers>',
type=int,
default=None,
help=_("Maximum number of servers to display. If limit equals -1,"
" all servers will be displayed. If limit is greater than"
" 'osapi_max_limit' option of Nova API,"
" 'osapi_max_limit' will be used instead."),
help=_("Maximum number of servers to display. If limit equals -1, "
"all servers will be displayed. If limit is greater than "
"'osapi_max_limit' option of Nova API, "
"'osapi_max_limit' will be used instead."),
)
parser.add_argument(
'--deleted',
@ -1295,13 +1295,12 @@ class RemoveFixedIP(command.Command):
parser.add_argument(
"server",
metavar="<server>",
help=_("Server (name or ID) to remove the fixed IP address from"),
help=_("Server to remove the fixed IP address from (name or ID)"),
)
parser.add_argument(
"ip_address",
metavar="<ip-address>",
help=_("Fixed IP address (IP address only) to remove from the "
"server"),
help=_("Fixed IP address to remove from the server (IP only)"),
)
return parser
@ -1322,14 +1321,14 @@ class RemoveFloatingIP(command.Command):
parser.add_argument(
"server",
metavar="<server>",
help=_("Server (name or ID) to remove the "
"floating IP address from"),
help=_(
"Server to remove the floating IP address from (name or ID)"
),
)
parser.add_argument(
"ip_address",
metavar="<ip-address>",
help=_("Floating IP address (IP address only) "
"to remove from server"),
help=_("Floating IP address to remove from server (IP only)"),
)
return parser

8
openstackclient/image/v2/image.py
View File

@ -463,17 +463,17 @@ class ListImage(command.Lister):
)
parser.add_argument(
"--limit",
metavar="<limit>",
metavar="<num-images>",
type=int,
help=_("Maximum number of images to display."),
)
parser.add_argument(
'--marker',
metavar='<marker>',
metavar='<image>',
default=None,
help=_("The last image (name or ID) of the previous page. Display "
help=_("The last image of the previous page. Display "
"list of images after marker. Display all images if not "
"specified."),
"specified. (name or ID)"),
)
return parser

6
openstackclient/network/v2/floating_ip.py
View File

@ -162,13 +162,13 @@ class CreateFloatingIP(common.NetworkAndComputeShowOne):
)
parser.add_argument(
'--floating-ip-address',
metavar='<floating-ip-address>',
metavar='<ip-address>',
dest='floating_ip_address',
help=_("Floating IP address")
)
parser.add_argument(
'--fixed-ip-address',
metavar='<fixed-ip-address>',
metavar='<ip-address>',
dest='fixed_ip_address',
help=_("Fixed IP address mapped to the floating IP")
)
@ -307,7 +307,7 @@ class ListFloatingIP(common.NetworkAndComputeLister):
)
parser.add_argument(
'--fixed-ip-address',
metavar='<fixed-ip-address>',
metavar='<ip-address>',
help=_("List floating IP(s) according to "
"given fixed IP address")
)

14
openstackclient/network/v2/port.py
View File

@ -301,7 +301,7 @@ class CreatePort(command.ShowOne):
metavar='subnet=<subnet>,ip-address=<ip-address>',
action=parseractions.MultiKeyValueAction,
optional_keys=['subnet', 'ip-address'],
help=_("Desired IP and/or subnet (name or ID) for this port: "
help=_("Desired IP and/or subnet for this port (name or ID): "
"subnet=<subnet>,ip-address=<ip-address> "
"(repeat option to set multiple fixed IP addresses)")
)
@ -496,9 +496,9 @@ class ListPort(command.Lister):
metavar='subnet=<subnet>,ip-address=<ip-address>',
action=parseractions.MultiKeyValueAction,
optional_keys=['subnet', 'ip-address'],
help=_("Desired IP and/or subnet (name or ID) for filtering "
"ports: subnet=<subnet>,ip-address=<ip-address> "
"(repeat option to set multiple fixed IP addresses)")
help=_("Desired IP and/or subnet for filtering ports "
"(name or ID): subnet=<subnet>,ip-address=<ip-address> "
"(repeat option to set multiple fixed IP addresses)"),
)
return parser
@ -593,7 +593,7 @@ class SetPort(command.Command):
metavar='subnet=<subnet>,ip-address=<ip-address>',
action=parseractions.MultiKeyValueAction,
optional_keys=['subnet', 'ip-address'],
help=_("Desired IP and/or subnet (name or ID) for this port: "
help=_("Desired IP and/or subnet for this port (name or ID): "
"subnet=<subnet>,ip-address=<ip-address> "
"(repeat option to set multiple fixed IP addresses)")
)
@ -757,8 +757,8 @@ class UnsetPort(command.Command):
metavar='subnet=<subnet>,ip-address=<ip-address>',
action=parseractions.MultiKeyValueAction,
optional_keys=['subnet', 'ip-address'],
help=_("Desired IP and/or subnet (name or ID) which should be "
"removed from this port: subnet=<subnet>,"
help=_("Desired IP and/or subnet which should be "
"removed from this port (name or ID): subnet=<subnet>,"
"ip-address=<ip-address> (repeat option to unset multiple "
"fixed IP addresses)"))

4
openstackclient/network/v2/subnet.py
View File

@ -428,14 +428,14 @@ class ListSubnet(command.Lister):
'--project',
metavar='<project>',
help=_("List only subnets which belong to a given project "
"(name or ID) in output")
"in output (name or ID)")
)
identity_common.add_project_domain_option_to_parser(parser)
parser.add_argument(
'--network',
metavar='<network>',
help=_("List only subnets which belong to a given network "
"(name or ID) in output")
"in output (name or ID)")
)
parser.add_argument(
'--gateway',

2
openstackclient/network/v2/subnet_pool.py
View File

@ -282,7 +282,7 @@ class ListSubnetPool(command.Lister):
'--address-scope',
metavar='<address-scope>',
help=_("List only subnet pools of given address scope "
"(name or ID) in output")
"in output (name or ID)")
)
return parser

2
openstackclient/object/v1/container.py
View File

@ -119,7 +119,7 @@ class ListContainer(command.Lister):
)
parser.add_argument(
"--limit",
metavar="<limit>",
metavar="<num-containers>",
type=int,
help=_("Limit the number of containers returned"),
)

2
openstackclient/object/v1/object.py
View File

@ -139,7 +139,7 @@ class ListObject(command.Lister):
)
parser.add_argument(
"--limit",
metavar="<limit>",
metavar="<num-objects>",
type=int,
help=_("Limit the number of objects returned"),
)

2
openstackclient/volume/v1/volume.py
View File

@ -291,7 +291,7 @@ class ListVolume(command.Lister):
'--limit',
type=int,
action=parseractions.NonNegativeAction,
metavar='<limit>',
metavar='<num-volumes>',
help=_('Maximum number of volumes to display'),
)
return parser

4
openstackclient/volume/v2/backup.py
View File

@ -202,14 +202,14 @@ class ListVolumeBackup(command.Lister):
)
parser.add_argument(
'--marker',
metavar='<marker>',
metavar='<volume-backup>',
help=_('The last backup of the previous page (name or ID)'),
)
parser.add_argument(
'--limit',
type=int,
action=parseractions.NonNegativeAction,
metavar='<limit>',
metavar='<num-backups>',
help=_('Maximum number of backups to display'),
)
parser.add_argument(

4
openstackclient/volume/v2/snapshot.py
View File

@ -146,14 +146,14 @@ class ListSnapshot(command.Lister):
)
parser.add_argument(
'--marker',
metavar='<marker>',
metavar='<snapshot>',
help=_('The last snapshot ID of the previous page'),
)
parser.add_argument(
'--limit',
type=int,
action=parseractions.NonNegativeAction,
metavar='<limit>',
metavar='<num-snapshots>',
help=_('Maximum number of snapshots to display'),
)
return parser

4
openstackclient/volume/v2/volume.py
View File

@ -341,14 +341,14 @@ class ListVolume(command.Lister):
)
parser.add_argument(
'--marker',
metavar='<marker>',
metavar='<volume>',
help=_('The last volume ID of the previous page'),
)
parser.add_argument(
'--limit',
type=int,
action=parseractions.NonNegativeAction,
metavar='<limit>',
metavar='<num-volumes>',
help=_('Maximum number of volumes to display'),
)
return parser

4
openstackclient/volume/v2/volume_snapshot.py
View File

@ -180,14 +180,14 @@ class ListVolumeSnapshot(command.Lister):
)
parser.add_argument(
'--marker',
metavar='<marker>',
metavar='<volume-snapshot>',
help=_('The last snapshot ID of the previous page'),
)
parser.add_argument(
'--limit',
type=int,
action=parseractions.NonNegativeAction,
metavar='<limit>',
metavar='<num-snapshots>',
help=_('Maximum number of snapshots to display'),
)
parser.add_argument(

2
openstackclient/volume/v2/volume_type.py
View File

@ -544,7 +544,7 @@ class UnsetVolumeType(command.Command):
'--project',
metavar='<project>',
help=_('Removes volume type access to project (name or ID) '
' (admin only)'),
'(admin only)'),
)
identity_common.add_project_domain_option_to_parser(parser)
parser.add_argument(