openstack/python-openstackclient
Code Issues Proposed changes

Start using 'cliff.sphinxext'

Browse Source 
'cliff', the command line library used by 'osc_lib' (and, thus,
'python-openstackclient') recently gained a Sphinx extension to
automatically document cliff commands. This allows us to use the
documentation we already have in code instead of duplicating it in the
documentation.

Introduce the use of this, starting with the 'server' commands. This
requires extending the descriptions for two commands to ensure no
information is lost.

Change-Id: If701af8d5a3f78f4b173ceb476dd0c163be4b6ca
This commit is contained in:
Stephen Finucane 2017-05-30 10:32:19 +01:00 committed by Steve Martinelli
parent 39673217dc
commit 9cfa12df2a
3 changed files with 87 additions and 970 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1015
doc/source/cli/command-objects/server.rst
View File

File diff suppressed because it is too large Load Diff

10
doc/source/conf.py
View File

@ -34,6 +34,7 @@ extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo',
'openstackdocstheme',
'stevedore.sphinxext',
'cliff.sphinxext',
]
# openstackdocstheme options
@ -269,3 +270,12 @@ texinfo_documents = [
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# -- Options for cliff.sphinxext plugin ---------------------------------------
autoprogram_cliff_application = 'openstack'
autoprogram_cliff_ignored = [
'--help', '--format', '--column', '--max-width', '--fit-width',
'--print-empty', '--prefix', '--noindent']

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

@ -394,10 +394,13 @@ class CreateServer(command.ShowOne):
disk_group.add_argument(
'--volume',
metavar='<volume>',
help=_(
'Create server using this volume as the boot disk '
'(name or ID)'
),
help=_('Create server using this volume as the boot disk (name '
'or ID).\n'
'This option automatically creates a block device mapping '
'with a boot index of 0. On many hypervisors (libvirt/kvm '
'for example) this will be device vda. Do not create a '
'duplicate mapping using --block-device-mapping for this '
'volume.'),
)
parser.add_argument(
'--flavor',
@ -489,8 +492,11 @@ class CreateServer(command.ShowOne):
type=_prefix_checked_value('net-id='),
help=_("Create a NIC on the server and connect it to network. "
"Specify option multiple times to create multiple NICs. "
"For more options on NICs see --nic parameter. "
"network: attach NIC to this network "),
"This is a wrapper for the '--nic net-id=<network>' "
"parameter that provides simple syntax for the standard "
"use case of connecting a new server to a given network. "
"For more advanced use cases, refer to the '--nic' "
"parameter."),
)
parser.add_argument(
'--port',
@ -500,8 +506,10 @@ class CreateServer(command.ShowOne):
type=_prefix_checked_value('port-id='),
help=_("Create a NIC on the server and connect it to port. "
"Specify option multiple times to create multiple NICs. "
"For more options on NICs see --nic parameter. "
"port: attach NIC this port "),
"This is a wrapper for the '--nic port-id=<pord>' "
"parameter that provides simple syntax for the standard "
"use case of connecting a new server to a given port. For "
"more advanced use cases, refer to the '--nic' parameter."),
)
parser.add_argument(
'--hint',
@ -1587,7 +1595,13 @@ class RescueServer(command.ShowOne):
class ResizeServer(command.Command):
_description = _("Scale server to a new flavor")
_description = _("""Scale server to a new flavor.
A resize operation is implemented by creating a new server and copying the
contents of the original disk into a new one. It is also a two-step process for
the user: the first is to perform the resize, the second is to either confirm
(verify) success and release the old server, or to declare a revert to release
the new server and restart the old one.""")
def get_parser(self, prog_name):
parser = super(ResizeServer, self).get_parser(prog_name)