From 4c0f3bfa89dfc9f207c4f6d6dc6ded85b86fee87 Mon Sep 17 00:00:00 2001 From: Eric Fried Date: Tue, 29 Oct 2019 16:22:18 -0500 Subject: [PATCH] common: autogenerate docs $namespace = openstack.common The subcommand documents for $namespace were hardcoded and thus prone to drift over time. This commit removes the hardcoded content and uses the autoprogram-cliff directive to generate them automatically from the subcommand configuration classes. This incorporates a correction to `openstack versions show`: The command `openstack versions show --help` showed a copy/paste error, using for the metavar for both --service and --status. Fix. Change-Id: I7658fed40d71f4c20ee27908ade433534657cfe5 Co-Authored-By: Pierre Prinetti Co-Authored-By: Matt Riedemann --- .../cli/command-objects/availability-zone.rst | 31 +- .../cli/command-objects/configuration.rst | 23 +- doc/source/cli/command-objects/extension.rst | 52 +--- doc/source/cli/command-objects/limits.rst | 34 +-- .../cli/command-objects/project-purge.rst | 35 +-- doc/source/cli/command-objects/quota.rst | 271 +----------------- doc/source/cli/command-objects/versions.rst | 47 +-- openstackclient/common/quota.py | 42 ++- openstackclient/common/versions.py | 15 +- 9 files changed, 56 insertions(+), 494 deletions(-) diff --git a/doc/source/cli/command-objects/availability-zone.rst b/doc/source/cli/command-objects/availability-zone.rst index d4c117a0f..bdc64f153 100644 --- a/doc/source/cli/command-objects/availability-zone.rst +++ b/doc/source/cli/command-objects/availability-zone.rst @@ -7,32 +7,5 @@ compute and network services. Block Storage v2, Compute v2, Network v2 -availability zone list ----------------------- - -List availability zones and their status - -.. program availability zone list -.. code:: bash - - openstack availability zone list - [--compute] - [--network] - [--volume] - [--long] - -.. option:: --compute - - List compute availability zones - -.. option:: --network - - List network availability zones - -.. option:: --volume - - List volume availability zones - -.. option:: --long - - List additional fields in output +.. autoprogram-cliff:: openstack.common + :command: availability zone list diff --git a/doc/source/cli/command-objects/configuration.rst b/doc/source/cli/command-objects/configuration.rst index 6e704d2d2..22fd13e43 100644 --- a/doc/source/cli/command-objects/configuration.rst +++ b/doc/source/cli/command-objects/configuration.rst @@ -6,24 +6,5 @@ Available for all services .. _configuration-show: -configuration show ------------------- - -Show the current openstack client configuration. This command is a little -different from other show commands because it does not take a resource name -or id to show. The command line options, such as --os-cloud, can be used to -show different configurations. - -.. program:: configuration show -.. code:: bash - - openstack configuration show - [--mask | --unmask] - -.. option:: --mask - - Attempt to mask passwords (default) - -.. option:: --unmask - - Show password in clear text +.. autoprogram-cliff:: openstack.common + :command: configuration show diff --git a/doc/source/cli/command-objects/extension.rst b/doc/source/cli/command-objects/extension.rst index 36cf418bb..1002a5fff 100644 --- a/doc/source/cli/command-objects/extension.rst +++ b/doc/source/cli/command-objects/extension.rst @@ -5,54 +5,6 @@ extension Many OpenStack server APIs include API extensions that enable additional functionality. -extension list --------------- -List API extensions - -.. program:: extension list -.. code:: bash - - openstack extension list - [--compute] - [--identity] - [--network] - [--volume] - [--long] - -.. option:: --compute - - List extensions for the Compute API - -.. option:: --identity - - List extensions for the Identity API - -.. option:: --network - - List extensions for the Network API - -.. option:: --volume - - List extensions for the Block Storage API - -.. option:: --long - - List additional fields in output - -extension show --------------- - -Show API extension - -.. program:: extension show -.. code:: bash - - openstack extension show - - -.. _extension_show: -.. describe:: - - Extension to display. Currently, only network extensions are supported. - (Name or Alias) +.. autoprogram-cliff:: openstack.common + :command: extension * diff --git a/doc/source/cli/command-objects/limits.rst b/doc/source/cli/command-objects/limits.rst index 926142095..3a0f99b37 100644 --- a/doc/source/cli/command-objects/limits.rst +++ b/doc/source/cli/command-objects/limits.rst @@ -6,36 +6,6 @@ The Compute and Block Storage APIs have resource usage limits. Compute v2, Block Storage v1 -limits show ------------ -Show compute and block storage limits - -.. program:: limits show -.. code:: bash - - openstack limits show - --absolute | --rate - [--reserved] - [--project ] - [--domain ] - -.. option:: --absolute - - Show absolute limits - -.. option:: --rate - - Show rate limits - -.. option:: --reserved - - Include reservations count [only valid with :option:`--absolute`] - -.. option:: --project - - Show limits for a specific project (name or ID) [only valid with :option:`--absolute`] - -.. option:: --domain - - Domain the project belongs to (name or ID) [only valid with :option:`--absolute`] +.. autoprogram-cliff:: openstack.common + :command: limits * diff --git a/doc/source/cli/command-objects/project-purge.rst b/doc/source/cli/command-objects/project-purge.rst index 0ad0bbf96..8f10a7745 100644 --- a/doc/source/cli/command-objects/project-purge.rst +++ b/doc/source/cli/command-objects/project-purge.rst @@ -6,37 +6,6 @@ Clean resources associated with a specific project. Block Storage v1, v2; Compute v2; Image v1, v2 -project purge -------------- -Clean resources associated with a project - -.. program:: project purge -.. code:: bash - - openstack project purge - [--dry-run] - [--keep-project] - [--auth-project | --project ] - [--project-domain ] - -.. option:: --dry-run - - List a project's resources - -.. option:: --keep-project - - Clean project resources, but don't delete the project. - -.. option:: --auth-project - - Delete resources of the project used to authenticate - -.. option:: --project - - Project to clean (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). This can be - used in case collisions between project names exist. +.. autoprogram-cliff:: openstack.common + :command: project purge diff --git a/doc/source/cli/command-objects/quota.rst b/doc/source/cli/command-objects/quota.rst index 25d0188a3..cab126524 100644 --- a/doc/source/cli/command-objects/quota.rst +++ b/doc/source/cli/command-objects/quota.rst @@ -7,272 +7,5 @@ single object with multiple properties. Block Storage v1, v2, Compute v2, Network v2 -quota list ----------- - -List quotas for all projects with non-default quota values - -.. program:: quota list -.. code:: bash - - openstack quota list - --compute | --network | --volume - [--project ] - [--detail] - -.. option:: --network - - List network quotas - -.. option:: --compute - - List compute quotas - -.. option:: --volume - - List volume quotas - -.. option:: --project - - List quotas for this project (name or ID) - -.. option:: --detail - - Show details about quotas usage - -quota set ---------- - -Set quotas for project - -.. program:: quota set -.. code:: bash - - openstack quota set - # Compute settings - [--cores ] - [--fixed-ips ] - [--floating-ips ] - [--injected-file-size ] - [--injected-files ] - [--instances ] - [--key-pairs ] - [--properties ] - [--ram ] - [--server-groups ] - [--server-group-members ] - - # Block Storage settings - [--backups ] - [--backup-gigabytes ] - [--gigabytes ] - [--per-volume-gigabytes ] - [--snapshots ] - [--volumes ] - [--volume-type ] - - # Network settings - [--floating-ips ] - [--secgroup-rules ] - [--secgroups ] - [--networks ] - [--subnets ] - [--ports ] - [--routers ] - [--rbac-policies ] - [--subnetpools ] - - - -Set quotas for class - -.. code:: bash - - openstack quota set - --class - # Compute settings - [--cores ] - [--fixed-ips ] - [--floating-ips ] - [--injected-file-size ] - [--injected-files ] - [--instances ] - [--key-pairs ] - [--properties ] - [--ram ] - [--server-groups ] - [--server-group-members ] - - # Block Storage settings - [--backups ] - [--backup-gigabytes ] - [--gigabytes ] - [--per-volume-gigabytes ] - [--snapshots ] - [--volumes ] - - - -.. option:: --class - - Set quotas for ```` - -.. option:: --properties - - New value for the properties quota - -.. option:: --ram - - New value for the ram quota - -.. option:: --secgroup-rules - - New value for the secgroup-rules quota - -.. option:: --instances - - New value for the instances quota - -.. option:: --key-pairs - - New value for the key-pairs quota - -.. option:: --fixed-ips - - New value for the fixed-ips quota - -.. option:: --secgroups - - New value for the secgroups quota - -.. option:: --injected-file-size - - New value for the injected-file-size quota - -.. option:: --server-groups - - New value for the server-groups quota - -.. option:: --server-group-members - - New value for the server-group-members quota - -.. option:: --floating-ips - - New value for the floating-ips quota - -.. option:: --injected-files - - New value for the injected-files quota - -.. option:: --cores - - New value for the cores quota - -.. option:: --injected-path-size - - New value for the injected-path-size quota - -.. option:: --backups - - New value for the backups quota - -.. option:: --backup-gigabytes - - New value for the backup gigabytes quota - -.. option:: --gigabytes - - New value for the gigabytes quota - -.. option:: --per-volume-gigabytes - - New value for the gigabytes quota of per volume - -.. option:: --volumes - - New value for the volumes quota - -.. option:: --snapshots - - New value for the snapshots quota - -.. option:: --volume-type - - Set quotas for a specific . The supported quotas are: - gigabytes, snapshots, volumes. - -.. option:: --networks - - New value for the networks quota - -.. option:: --subnets - - New value for the subnets quota - -.. option:: --ports - - New value for the ports quota - -.. option:: --routers - - New value for the routers quota - -.. option:: --rbac-policies - - New value for the rbac-policies quota - -.. option:: --vips - - New value for the vips quota - -.. option:: --subnetpools - - New value for the subnetpools quota - -.. option:: --members - - New value for the members quota - -.. option:: --health-monitors - - New value for the health-monitors quota - -quota show ----------- - -Show quotas for project or class. Specify ``--os-compute-api-version 2.50`` or -higher to see ``server-groups`` and ``server-group-members`` output for a given -quota class. - -.. program:: quota show -.. code:: bash - - openstack quota show - [--default] - [] - - -.. option:: --default - - Show default quotas for :ref:`\ ` - -.. _quota_show-project: -.. describe:: - - Show quotas for this project (name or ID) - -.. code:: bash - - openstack quota show - --class - [] - -.. option:: --class - - Show quotas for :ref:`\ ` - -.. _quota_show-class: -.. describe:: - - Show quotas for this class (name or ID) +.. autoprogram-cliff:: openstack.common + :command: quota * diff --git a/doc/source/cli/command-objects/versions.rst b/doc/source/cli/command-objects/versions.rst index 0aa9a1b78..ebebec192 100644 --- a/doc/source/cli/command-objects/versions.rst +++ b/doc/source/cli/command-objects/versions.rst @@ -4,48 +4,5 @@ versions Get a list of every version of every service in a given cloud. -versions show -------------- - -Show service versions: - -.. program:: versions show -.. code:: bash - - openstack versions show - [--all-interfaces] - [--interface ] - [--region-name ] - [--service ] - [--status ] - -.. option:: --all-interfaces - - Return results for every interface of every service. - [Mutually exclusive with --interface] - -.. option:: --interface - - Limit results to only those on given interface. - [Default 'public'. Mutually exclusive with --all-interfaces] - -.. option:: --region-name - - Limit results to only those from a given region. - -.. option:: --service - - Limit results to only those for service. The argument should be either - an exact match to what is in the catalog or a known official value or - alias from `service-types-authority`_. - -.. option:: --status - - Limit results to only those in the given state. Valid values are: - - - SUPPORTED - - CURRENT - - DEPRECATED - - EXPERIMENTAL - -.. _service-types-authority: https://service-types.openstack.org/ +.. autoprogram-cliff:: openstack.common + :command: versions show diff --git a/openstackclient/common/quota.py b/openstackclient/common/quota.py index fb4e86031..80c8749ac 100644 --- a/openstackclient/common/quota.py +++ b/openstackclient/common/quota.py @@ -24,6 +24,7 @@ from osc_lib import utils import six from openstackclient.i18n import _ +from openstackclient.network import common LOG = logging.getLogger(__name__) @@ -457,18 +458,37 @@ class ListQuota(command.Lister, BaseQuota): return ((), ()) -class SetQuota(command.Command): +class SetQuota(common.NetDetectionMixin, command.Command): _description = _("Set quotas for project or class") def _build_options_list(self): - if self.app.client_manager.is_network_endpoint_enabled(): - return itertools.chain(COMPUTE_QUOTAS.items(), - VOLUME_QUOTAS.items(), - NETWORK_QUOTAS.items()) - else: - return itertools.chain(COMPUTE_QUOTAS.items(), - VOLUME_QUOTAS.items(), - NOVA_NETWORK_QUOTAS.items()) + help_fmt = _('New value for the %s quota') + # Compute and volume quota options are always the same + rets = [(k, v, help_fmt % v) for k, v in itertools.chain( + COMPUTE_QUOTAS.items(), + VOLUME_QUOTAS.items(), + )] + # For docs build, we want to produce helps for both neutron and + # nova-network options. They overlap, so we have to figure out which + # need to be tagged as specific to one network type or the other. + if self.is_docs_build: + # NOTE(efried): This takes advantage of the fact that we know the + # nova-net options are a subset of the neutron options. If that + # ever changes, this algorithm will need to be adjusted accordingly + inv_compute = set(NOVA_NETWORK_QUOTAS.values()) + for k, v in NETWORK_QUOTAS.items(): + _help = help_fmt % v + if v not in inv_compute: + # This one is unique to neutron + _help = self.enhance_help_neutron(_help) + rets.append((k, v, _help)) + elif self.is_neutron: + rets.extend( + [(k, v, help_fmt % v) for k, v in NETWORK_QUOTAS.items()]) + elif self.is_nova_network: + rets.extend( + [(k, v, help_fmt % v) for k, v in NOVA_NETWORK_QUOTAS.items()]) + return rets def get_parser(self, prog_name): parser = super(SetQuota, self).get_parser(prog_name) @@ -484,13 +504,13 @@ class SetQuota(command.Command): default=False, help=_('Set quotas for '), ) - for k, v in self._build_options_list(): + for k, v, h in self._build_options_list(): parser.add_argument( '--%s' % v, metavar='<%s>' % v, dest=k, type=int, - help=_('New value for the %s quota') % v, + help=h, ) parser.add_argument( '--volume-type', diff --git a/openstackclient/common/versions.py b/openstackclient/common/versions.py index e6781bc66..3acd9f73d 100644 --- a/openstackclient/common/versions.py +++ b/openstackclient/common/versions.py @@ -46,14 +46,21 @@ class ShowVersions(command.Lister): parser.add_argument( '--service', metavar='', - help=_('Show versions for a specific service.'), + help=_('Show versions for a specific service. The argument should ' + 'be either an exact match to what is in the catalog or a ' + 'known official value or alias from ' + 'service-types-authority ' + '(https://service-types.openstack.org/)'), ) parser.add_argument( '--status', metavar='', - help=_('Show versions for a specific status.' - ' [Valid values are SUPPORTED, CURRENT,' - ' DEPRECATED, EXPERIMENTAL]'), + help=_("""Show versions for a specific status. Valid values are: + +- SUPPORTED +- CURRENT +- DEPRECATED +- EXPERIMENTAL""") ) return parser