Merge "Start using 'cliff.sphinxext'"

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 ce4191c1..151c6783 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',
@@ -1591,7 +1599,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)