Start using 'cliff.sphinxext'

'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

3 files changed, 87 insertions, 970 deletions

diff --git a/doc/source/cli/command-objects/server.rst b/doc/source/cli/command-objects/server.rst
index 11182822..a7fef257 100644
--- a/doc/source/cli/command-objects/server.rst
+++ b/doc/source/cli/command-objects/server.rst
@@ -4,990 +4,83 @@ server
 
 Compute v2
 
-server add fixed ip
--------------------
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server add *
 
-Add fixed IP address to server
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server create
 
-.. program:: server add fixed ip
-.. code:: bash
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server delete
 
-    openstack server add fixed ip
-        [--fixed-ip-address <ip-address>]
-        <server>
-        <network>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server dump create
 
-.. option:: --fixed-ip-address <ip-address>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server list
 
-    Requested fixed IP address
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server lock
 
-.. describe:: <server>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server migrate
 
-    Server to receive the fixed IP address (name or ID)
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server pause
 
-.. describe:: <network>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server reboot
 
-    Network to allocate the fixed IP address from (name or ID)
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server rebuild
 
-server add floating ip
-----------------------
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server remove *
 
-Add floating IP address to server
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server rescue
 
-.. program:: server add floating ip
-.. code:: bash
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server resize
 
-    openstack server add floating ip
-        [--fixed-ip-address <ip-address>]
-        <server>
-        <ip-address>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server restore
 
-.. option:: --fixed-ip-address <ip-address>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server resume
 
-    Fixed IP address to associate with this floating IP address
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server set
 
-.. describe:: <server>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server shelve
 
-    Server to receive the floating IP address (name or ID)
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server show
 
-.. describe:: <ip-address>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server ssh
 
-    Floating IP address to assign to server (IP only)
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server start
 
-server add port
----------------
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server stop
 
-Add port to server
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server suspend
 
-.. program:: server add port
-.. code:: bash
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server unlock
 
-    openstack server add port
-        <server>
-        <port>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server unpause
 
-.. describe:: <server>
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server unrescue
 
-    Server to add the port to (name or ID)
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server unset
 
-.. describe:: <port>
-
-    Port to add to the server (name or ID)
-
-server add security group
--------------------------
-
-Add security group to server
-
-.. program:: server add security group
-.. code:: bash
-
-    openstack server add security group
-        <server>
-        <group>
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-.. describe:: <group>
-
-    Security group to add (name or ID)
-
-server add volume
------------------
-
-Add volume to server
-
-.. program:: server add volume
-.. code:: bash
-
-    openstack server add volume
-        [--device <device>]
-        <server>
-        <volume>
-
-.. option:: --device <device>
-
-    Server internal device name for volume
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-.. describe:: <volume>
-
-    Volume to add (name or ID)
-
-server create
--------------
-
-Create a new server
-
-.. program:: server create
-.. code:: bash
-
-    openstack server create
-        --image <image> | --volume <volume>
-        --flavor <flavor>
-        [--security-group <security-group-name> [...] ]
-        [--key-name <key-name>]
-        [--property <key=value> [...] ]
-        [--file <dest-filename=source-filename>] [...] ]
-        [--user-data <user-data>]
-        [--availability-zone <zone-name>]
-        [--block-device-mapping <dev-name=mapping> [...] ]
-        [--nic <net-id=net-uuid,v4-fixed-ip=ip-addr,v6-fixed-ip=ip-addr,port-id=port-uuid,auto,none> [...] ]
-        [--network <network>]
-        [--port <port>]
-        [--hint <key=value> [...] ]
-        [--config-drive <value>|True ]
-        [--min <count>]
-        [--max <count>]
-        [--wait]
-        <server-name>
-
-.. option:: --image <image>
-
-    Create server boot disk from this image (name or ID)
-
-.. option:: --volume <volume>
-
-    Create server using this volume as the boot disk (name or ID)
-
-    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
-    :option:`--block-device-mapping` for this volume.
-
-.. option:: --flavor <flavor>
-
-    Create server with this flavor (name or ID)
-
-.. option:: --security-group <security-group>
-
-    Security group to assign to this server (name or ID)
-    (repeat option to set multiple groups)
-
-.. option:: --key-name <key-name>
-
-    Keypair to inject into this server (optional extension)
-
-.. option:: --property <key=value>
-
-    Set a property on this server
-    (repeat option to set multiple values)
-
-.. option:: --file <dest-filename=source-filename>
-
-    File to inject into image before boot
-    (repeat option to set multiple files)
-
-.. option:: --user-data <user-data>
-
-    User data file to serve from the metadata server
-
-.. option:: --availability-zone <zone-name>
-
-    Select an availability zone for the server
-
-.. option:: --block-device-mapping <dev-name=mapping>
-
-    Create a block device on the server.
-
-    Block device mapping in the format
-
-    <dev-name>=<id>:<type>:<size(GB)>:<delete-on-terminate>
-
-    <dev-name>: block device name, like: vdb, xvdc (required)
-
-    <id>: UUID of the volume or snapshot (required)
-
-    <type>: volume or snapshot; default: volume (optional)
-
-    <size(GB)>: volume size if create from snapshot (optional)
-
-    <delete-on-terminate>: true or false; default: false (optional)
-
-    (optional extension)
-
-.. option:: --nic <net-id=net-uuid,v4-fixed-ip=ip-addr,v6-fixed-ip=ip-addr,port-id=port-uuid,auto,none>
-
-    Create a NIC on the server. Specify option multiple times to create
-    multiple NICs. Either net-id or port-id must be provided, but not both.
-    net-id: attach NIC to network with this UUID,
-    port-id: attach NIC to port with this UUID,
-    v4-fixed-ip: IPv4 fixed address for NIC (optional),
-    v6-fixed-ip: IPv6 fixed address for NIC (optional).
-    none: (v2.37+) no network is attached.
-    auto: (v2.37+) the compute service will automatically allocate a network.
-    Specifying a --nic of auto or none cannot be used with any other
-    --nic value.
-
-.. option:: --network <network>
-
-    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
-
-.. option:: --port <port>
-
-    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 to this port
-
-.. option:: --hint <key=value>
-
-    Hints for the scheduler (optional extension)
-
-.. option:: --config-drive <config-drive-volume>|True
-
-    Use specified volume as the config drive, or 'True' to use an ephemeral drive
-
-.. option:: --min <count>
-
-    Minimum number of servers to launch (default=1)
-
-.. option:: --max <count>
-
-    Maximum number of servers to launch (default=1)
-
-.. option:: --wait
-
-    Wait for build to complete
-
-.. describe:: <server-name>
-
-    New server name
-
-..
-
-The parameters ``--network <network>`` and ``--port <port>`` are actually
-wrappers to ``--nic net-id=<network>`` and ``--nic port-id=<port>``. ``--nic``
-also provides additional options to specify an IP address, automatic network
-assignment and NICs which are not assigned to any port. This functionality
-is not part of ``--network`` and ``--port``, which aim to provide a simple
-syntax for the standard use cases of connecting a new server to a given
-network or port.
-
-server delete
--------------
-
-Delete server(s)
-
-.. program:: server delete
-.. code:: bash
-
-    openstack server delete
-        <server> [<server> ...] [--wait]
-
-.. option:: --wait
-
-    Wait for delete to complete
-
-.. describe:: <server>
-
-    Server(s) to delete (name or ID)
-
-server dump create
-------------------
-Create a dump file in server(s)
-
-Trigger crash dump in server(s) with features like kdump in Linux. It will
-create a dump file in the server(s) dumping the server(s)' memory, and also
-crash the server(s). OSC sees the dump file (server dump) as a kind of
-resource.
-
-.. program:: server dump create
-.. code:: bash
-
-    openstack server dump create
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to create dump file (name or ID)
-
-server list
------------
-
-List servers
-
-.. code:: bash
-
-    openstack server list
-        [--reservation-id <reservation-id>]
-        [--ip <ip-address-regex>]
-        [--ip6 <ip6-address-regex>]
-        [--name <name-regex>]
-        [--instance-name <instance-name-regex>]
-        [--status <status>]
-        [--flavor <flavor>]
-        [--image <image>]
-        [--host <hostname>]
-        [--all-projects]
-        [--project <project> [--project-domain <project-domain>]]
-        [--long]
-        [--no-name-lookup | -n]
-        [--marker <server>]
-        [--limit <num-servers>]
-        [--deleted]
-        [--changes-since <changes-since>]
-
-.. option:: --reservation-id <reservation-id>
-
-    Only return instances that match the reservation
-
-.. option:: --ip <ip-address-regex>
-
-    Regular expression to match IP addresses
-
-.. option:: --ip6 <ip-address-regex>
-
-    Regular expression to match IPv6 addresses
-
-.. option:: --name <name-regex>
-
-    Regular expression to match names
-
-.. option:: --instance-name <server-name-regex>
-
-    Regular expression to match instance name (admin only)
-
-.. option:: --status <status>
-
-    Search by server status
-
-.. option:: --flavor <flavor>
-
-    Search by flavor (name or ID)
-
-.. option:: --image <image>
-
-    Search by image (name or ID)
-
-.. option:: --host <hostname>
-
-    Search by hostname
-
-.. option:: --all-projects
-
-    Include all projects (admin only)
-
-.. option:: --project <project>
-
-    Search by project (admin only) (name or ID)
-
-.. option:: --project-domain <project-domain>
-
-    Domain the project belongs to (name or ID).
-    This can be used in case collisions between project names exist.
-
-.. option:: --user <user>
-
-    Search by user (admin only) (name or ID)
-
-.. option:: --user-domain <user-domain>
-
-    Domain the user belongs to (name or ID).
-    This can be used in case collisions between user names exist.
-
-.. option:: --long
-
-    List additional fields in output
-
-.. option:: --no-name-lookup
-
-    Skips image and flavor names lookup
-
-    ``-n`` may be used as an alias for this option.
-
-.. option:: --marker <server>
-
-    The last server of the previous page. Display list of servers
-    after marker. Display all servers if not specified. (name or ID)
-
-.. 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
-    API, 'osapi_max_limit' will be used instead.
-
-.. option:: --deleted
-
-    Only display deleted servers (Admin only).
-
-.. option:: --changes-since <changes-since>
-
-    List only servers changed after a certain point of time. The provided time
-    should be an ISO 8061 formatted time. ex 2016-03-04T06:27:59Z.
-
-server lock
------------
-
-Lock server(s). A non-admin user will not be able to execute actions
-
-.. program:: server lock
-.. code:: bash
-
-    openstack server lock
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to lock (name or ID)
-
-server migrate
---------------
-
-Migrate server to different host
-
-.. program:: server migrate
-.. code:: bash
-
-    openstack server migrate
-        --live <host>
-        [--shared-migration | --block-migration]
-        [--disk-overcommit | --no-disk-overcommit]
-        [--wait]
-        <server>
-
-.. option:: --live <hostname>
-
-    Target hostname
-
-.. option:: --shared-migration
-
-    Perform a shared live migration (default)
-
-.. option:: --block-migration
-
-    Perform a block live migration
-
-.. option:: --disk-overcommit
-
-    Allow disk over-commit on the destination host
-
-.. option:: --no-disk-overcommit
-
-    Do not over-commit disk on the destination host (default)
-
-.. option:: --wait
-
-    Wait for migrate to complete
-
-.. describe:: <server>
-
-    Server to migrate (name or ID)
-
-server pause
-------------
-
-Pause server(s)
-
-.. program:: server pause
-.. code:: bash
-
-    openstack server pause
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to pause (name or ID)
-
-server reboot
--------------
-
-Perform a hard or soft server reboot
-
-.. program:: server reboot
-.. code:: bash
-
-    openstack server reboot
-        [--hard | --soft]
-        [--wait]
-        <server>
-
-.. option:: --hard
-
-    Perform a hard reboot
-
-.. option:: --soft
-
-    Perform a soft reboot
-
-.. option:: --wait
-
-    Wait for reboot to complete
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server rebuild
---------------
-
-Rebuild server
-
-.. program:: server rebuild
-.. code:: bash
-
-    openstack server rebuild
-        [--image <image>]
-        [--password <password>]
-        [--wait]
-        <server>
-
-.. option:: --image <image>
-
-    Recreate server from the specified image (name or ID). Defaults to the
-    currently used one.
-
-.. option:: --password <password>
-
-    Set the password on the rebuilt instance
-
-.. option:: --wait
-
-    Wait for rebuild to complete
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server remove fixed ip
-----------------------
-
-Remove fixed IP address from server
-
-.. program:: server remove fixed ip
-.. code:: bash
-
-    openstack server remove fixed ip
-        <server>
-        <ip-address>
-
-.. describe:: <server>
-
-    Server to remove the fixed IP address from (name or ID)
-
-.. describe:: <ip-address>
-
-    Fixed IP address to remove from the server (IP only)
-
-server remove floating ip
--------------------------
-
-Remove floating IP address from server
-
-.. program:: server remove floating ip
-.. code:: bash
-
-    openstack server remove floating ip
-        <server>
-        <ip-address>
-
-.. describe:: <server>
-
-    Server to remove the floating IP address from (name or ID)
-
-.. describe:: <ip-address>
-
-    Floating IP address to remove from server (IP only)
-
-server remove port
-------------------
-
-Remove port from server
-
-.. program:: server remove port
-.. code:: bash
-
-    openstack server remove port
-        <server>
-        <port>
-
-.. describe:: <server>
-
-    Server to remove the port from (name or ID)
-
-.. describe:: <port>
-
-    Port to remove from the server (name or ID)
-
-server remove security group
-----------------------------
-
-Remove security group from server
-
-.. program:: server remove security group
-.. code:: bash
-
-    openstack server remove security group
-        <server>
-        <group>
-
-.. describe:: <server>
-
-    Name or ID of server to use
-
-.. describe:: <group>
-
-    Name or ID of security group to remove from server
-
-server remove volume
---------------------
-
-Remove volume from server
-
-.. program:: server remove volume
-.. code:: bash
-
-    openstack server remove volume
-        <server>
-        <volume>
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-.. describe:: <volume>
-
-    Volume to remove (name or ID)
-
-server rescue
--------------
-
-Put server in rescue mode
-
-.. program:: server rescue
-.. code:: bash
-
-    openstack server rescue
-        <server>
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server resize
--------------
-
-Scale server to a new flavor
-
-.. program:: server resize
-.. code:: bash
-
-    openstack server resize
-        --flavor <flavor>
-        [--wait]
-        <server>
-
-    openstack server resize
-        --confirm | --revert
-        <server>
-
-.. option:: --flavor <flavor>
-
-    Resize server to specified flavor
-
-.. option:: --confirm
-
-    Confirm server resize is complete
-
-.. option:: --revert
-
-    Restore server state before resize
-
-.. option:: --wait
-
-    Wait for resize to complete
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-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.
-
-server restore
---------------
-
-Restore server(s) from soft-deleted state
-
-.. program:: server restore
-.. code:: bash
-
-    openstack server restore
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to restore (name or ID)
-
-server resume
--------------
-
-Resume server(s)
-
-.. program:: server resume
-.. code:: bash
-
-    openstack server resume
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to resume (name or ID)
-
-server set
-----------
-
-Set server properties
-
-.. program:: server set
-.. code:: bash
-
-    openstack server set
-        --name <new-name>
-        --property <key=value>
-        [--property <key=value>] ...
-        --root-password
-        --state <state>
-        <server>
-
-.. option:: --name <new-name>
-
-    New server name
-
-.. option:: --root-password
-
-    Set new root password (interactive only)
-
-.. option:: --property <key=value>
-
-    Property to add/change for this server
-    (repeat option to set multiple properties)
-
-.. option:: --state <state>
-
-    New server state (valid value: active, error)
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server shelve
--------------
-
-Shelve server(s)
-
-.. program:: server shelve
-.. code:: bash
-
-    openstack server shelve
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to shelve (name or ID)
-
-server show
------------
-
-Show server details
-
-.. program:: server show
-.. code:: bash
-
-    openstack server show
-        [--diagnostics]
-        <server>
-
-.. option:: --diagnostics
-
-    Display server diagnostics information
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server ssh
-----------
-
-SSH to server
-
-.. program:: server ssh
-.. code:: bash
-
-    openstack server ssh
-        [--login <login-name>]
-        [--port <port>]
-        [--identity <keyfile>]
-        [--option <config-options>]
-        [--public | --private | --address-type <address-type>]
-        <server>
-
-.. option:: --login <login-name>
-
-    Login name (ssh -l option)
-
-.. option:: --port <port>
-
-    Destination port (ssh -p option)
-
-.. option:: --identity <keyfile>
-
-    Private key file (ssh -i option)
-
-.. option:: --option <config-options>
-
-    Options in ssh_config(5) format (ssh -o option)
-
-.. option:: --public
-
-    Use public IP address
-
-.. option:: --private
-
-    Use private IP address
-
-.. option:: --address-type <address-type>
-
-    Use other IP address (public, private, etc)
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server start
-------------
-
-Start server(s)
-
-.. program:: server start
-.. code:: bash
-
-    openstack server start
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to start (name or ID)
-
-server stop
------------
-
-Stop server(s)
-
-.. program:: server stop
-.. code:: bash
-
-    openstack server stop
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to stop (name or ID)
-
-server suspend
---------------
-
-Suspend server(s)
-
-.. program:: server suspend
-.. code:: bash
-
-    openstack server suspend
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to suspend (name or ID)
-
-server unlock
--------------
-
-Unlock server(s)
-
-.. program:: server unlock
-.. code:: bash
-
-    openstack server unlock
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to unlock (name or ID)
-
-server unpause
---------------
-
-Unpause server(s)
-
-.. program:: server unpause
-.. code:: bash
-
-    openstack server unpause
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-   Server(s) to unpause (name or ID)
-
-server unrescue
----------------
-
-Restore server from rescue mode
-
-.. program:: server unrescue
-.. code:: bash
-
-    openstack server unrescue
-        <server>
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server unset
-------------
-
-Unset server properties
-
-.. program:: server unset
-.. code:: bash
-
-    openstack server unset
-        --property <key>
-        [--property <key>] ...
-        <server>
-
-.. option:: --property <key>
-
-    Property key to remove from server
-    (repeat option to remove multiple values)
-
-.. describe:: <server>
-
-    Server (name or ID)
-
-server unshelve
----------------
-
-Unshelve server(s)
-
-.. program:: server unshelve
-.. code:: bash
-
-    openstack server unshelve
-        <server> [<server> ...]
-
-.. describe:: <server>
-
-    Server(s) to unshelve (name or ID)
+.. autoprogram-cliff:: openstack.compute.v2
+   :command: server unshelve
diff --git a/doc/source/conf.py b/doc/source/conf.py
index fc7520fd..bd4fa730 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -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']
diff --git a/openstackclient/compute/v2/server.py b/openstackclient/compute/v2/server.py
index a991ed45..d4d8c923 100644
--- a/openstackclient/compute/v2/server.py
+++ b/openstackclient/compute/v2/server.py
@@ -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)