From 34975edd1456b65986f24f8b17390e3ef99b4ac4 Mon Sep 17 00:00:00 2001
From: Steve Martinelli <stevemar@ca.ibm.com>
Date: Mon, 5 Jan 2015 01:36:35 -0500
Subject: [PATCH] tweak the server command docs

the formatting used for the server commands is not the same as
the other command docs, this patch addresses that issue.

Change-Id: I5f31cf6a317d9eb35ec46185800fade3dd956dc4
---
 doc/source/command-objects/server.rst | 246 +++++++++++++++++---------
 1 file changed, 164 insertions(+), 82 deletions(-)

diff --git a/doc/source/command-objects/server.rst b/doc/source/command-objects/server.rst
index 2f5aef1070..48cefe6ada 100644
--- a/doc/source/command-objects/server.rst
+++ b/doc/source/command-objects/server.rst
@@ -14,10 +14,12 @@ Add security group to server
         <server>
         <group>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
-:option:`<group>`
+.. describe:: <group>
+
     Security group to add (name or ID)
 
 server add volume
@@ -32,13 +34,16 @@ Add volume to server
         <server>
         <volume>
 
-:option:`--device` <device>
+.. option:: --device <device>
+
     Server internal device name for volume
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
-:option:`<volume>`
+.. describe:: <volume>
+
     Volume to add (name or ID)
 
 server create
@@ -66,55 +71,72 @@ Create a new server
         [--wait]
         <server-name>
 
-:option:`--image` <image>
+.. option:: --image <image>
+
     Create server from this image
 
-:option:`--volume` <volume>
+.. option:: --volume <volume>
+
     Create server from this volume
 
-:option:`--flavor` <flavor>
+.. option:: --flavor <flavor>
+
     Create server with this flavor
 
-:option:`--security-group` <security-group-name>
+.. option:: --security-group <security-group-name>
+
     Security group to assign to this server (repeat for multiple groups)
 
-:option:`--key-name` <key-name>
+.. option:: --key-name <key-name>
+
     Keypair to inject into this server (optional extension)
 
-:option:`--property` <key=value>
+.. option:: --property <key=value>
+
     Set a property on this server (repeat for multiple values)
 
-:option:`--file` <dest-filename=source-filename>
+.. option:: --file <dest-filename=source-filename>
+
     File to inject into image before boot (repeat for multiple files)
 
-:option:`--user-data` <user-data>
+.. option:: --user-data <user-data>
+
     User data file to serve from the metadata server
 
-:option:`--availability-zone` <zone-name>
+.. option:: --availability-zone <zone-name>
+
     Select an availability zone for the server
 
-:option:`--block-device-mapping` <dev-name=mapping>
+.. option:: --block-device-mapping <dev-name=mapping>
+
     Map block devices; map is <id>:<type>:<size(GB)>:<delete_on_terminate> (optional extension)
 
-:option:`--nic` <nic-config-string>
+.. option:: --nic <nic-config-string>
+
     Specify NIC configuration (optional extension)
 
-:option:`--hint` <key=value>
+.. option:: --hint <key=value>
+
     Hints for the scheduler (optional extension)
 
-:option:`--config-drive` <config-drive-volume>|True
+.. option:: --config-drive <config-drive-volume>|True
+
     Use specified volume as the config drive, or 'True' to use an ephemeral drive
 
-:option:`--min` <count>
+.. option:: --min <count>
+
     Minimum number of servers to launch (default=1)
 
-:option:`--max` <count>
+.. option:: --max <count>
+
     Maximum number of servers to launch (default=1)
 
-:option:`--wait`
+.. option:: --wait
+
     Wait for build to complete
 
-:option:`<server-name>`
+.. describe:: <server-name>
+
     New server name
 
 server delete
@@ -127,7 +149,8 @@ Delete server(s)
     os server delete
         <server> [<server> ...]
 
-:option:`<server>`
+.. describe:: <server>
+
     Server to delete (name or ID)
 
 server list
@@ -150,37 +173,48 @@ List servers
         [--all-projects]
         [--long]
 
-:option:`--reservation-id` <reservation-id>
+.. option:: --reservation-id <reservation-id>
+
     Only return instances that match the reservation
 
-:option:`--ip` <ip-address-regex>
+.. option:: --ip <ip-address-regex>
+
     Regular expression to match IP addresses
 
-:option:`--ip6` <ip-address-regex>
+.. option:: --ip6 <ip-address-regex>
+
     Regular expression to match IPv6 addresses
 
-:option:`--name` <name-regex>
+.. option:: --name <name-regex>
+
     Regular expression to match names
 
-:option:`--instance-name` <server-name-regex>
+.. option:: --instance-name <server-name-regex>
+
     Regular expression to match instance name (admin only)
 
-:option:`--status` <status>
+.. option:: --status <status>
+
     Search by server status
 
-:option:`--flavor` <flavor>
+.. option:: --flavor <flavor>
+
     Search by flavor ID
 
-:option:`--image` <image>
+.. option:: --image <image>
+
     Search by image ID
 
-:option:`--host` <hostname>
+.. option:: --host <hostname>
+
     Search by hostname
 
-:option:`--all-projects`
+.. option:: --all-projects
+
     Include all projects (admin only)
 
-:option:`--long`
+.. option:: --long
+
     List additional fields in output
 
 server lock
@@ -193,7 +227,8 @@ Lock server
     os server lock
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server migrate
@@ -210,25 +245,32 @@ Migrate server to different host
         [--wait]
         <server>
 
-:option:`--live` <hostname>
+.. option:: --live <hostname>
+
     Target hostname
 
-:option:`--shared-migration`
+.. option:: --shared-migration
+
     Perform a shared live migration (default)
 
-:option:`--block-migration`
+.. option:: --block-migration
+
     Perform a block live migration
 
-:option:`--disk-overcommit`
+.. option:: --disk-overcommit
+
     Allow disk over-commit on the destination host
 
-:option:`--no-disk-overcommit`
+.. option:: --no-disk-overcommit
+
     Do not over-commit disk on the destination host (default)
 
-:option:`--wait`
+.. option:: --wait
+
     Wait for resize to complete
 
-:option:`<server>`
+.. describe:: <server>
+
     Server to migrate (name or ID)
 
 server pause
@@ -241,7 +283,8 @@ Pause server
     os server pause
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server reboot
@@ -256,16 +299,20 @@ Perform a hard or soft server reboot
         [--wait]
         <server>
 
-:option:`--hard`
+.. option:: --hard
+
     Perform a hard reboot
 
-:option:`--soft`
+.. option:: --soft
+
     Perform a soft reboot
 
-:option:`--wait`
+.. option:: --wait
+
     Wait for reboot to complete
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server rebuild
@@ -281,16 +328,20 @@ Rebuild server
         [--wait]
         <server>
 
-:option:`--image` <image>
+.. option:: --image <image>
+
     Recreate server from this image
 
-:option:`--password` <password>
+.. option:: --password <password>
+
     Set the password on the rebuilt instance
 
-:option:`--wait`
+.. option:: --wait
+
     Wait for rebuild to complete
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server remove security group
@@ -304,10 +355,12 @@ Remove security group from server
         <server>
         <group>
 
-:option:`<server>`
+.. describe:: <server>
+
     Name or ID of server to use
 
-:option:`<group>`
+.. describe:: <group>
+
     Name or ID of security group to remove from server
 
 server remove volume
@@ -321,10 +374,12 @@ Remove volume from server
         <server>
         <volume>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
-:option:`<volume>`
+.. describe:: <volume>
+
     Volume to remove (name or ID)
 
 server rescue
@@ -337,7 +392,8 @@ Put server in rescue mode
     os server rescue
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server resize
@@ -356,19 +412,24 @@ Scale server to a new flavor
         --verify | --revert
         <server>
 
-:option:`--flavor` <flavor>
+.. option:: --flavor <flavor>
+
     Resize server to specified flavor
 
-:option:`--verify`
+.. option:: --verify
+
     Verify server resize is complete
 
-:option:`--revert`
+.. option:: --revert
+
     Restore server state before resize
 
-:option:`--wait`
+.. option:: --wait
+
     Wait for resize to complete
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 A resize operation is implemented by creating a new server and copying
@@ -387,7 +448,8 @@ Resume server
     os server resume
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server set
@@ -404,17 +466,21 @@ Set server properties
         --root-password
         <server>
 
-:option:`--name` <new-name>
+.. option:: --name <new-name>
+
     New server name
 
-:option:`--root-password`
+.. option:: --root-password
+
     Set new root password (interactive only)
 
-:option:`--property` <key=value>
+.. option:: --property <key=value>
+
     Property to add/change for this server (repeat option to set
     multiple properties)
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server show
@@ -428,10 +494,12 @@ Show server details
         [--diagnostics]
         <server>
 
-:option:`--diagnostics`
+.. option:: --diagnostics
+
     Display server diagnostics information
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server ssh
@@ -449,28 +517,36 @@ Ssh to server
         [--public | --private | --address-type <address-type>]
         <server>
 
-:option:`--login` <login-name>
+.. option:: --login <login-name>
+
     Login name (ssh -l option)
 
-:option:`--port` <port>
+.. option:: --port <port>
+
     Destination port (ssh -p option)
 
-:option:`--identity` <keyfile>
+.. option:: --identity <keyfile>
+
     Private key file (ssh -i option)
 
-:option:`--option` <config-options>
+.. option:: --option <config-options>
+
     Options in ssh_config(5) format (ssh -o option)
 
-:option:`--public`
+.. option:: --public
+
     Use public IP address
 
-:option:`--private`
+.. option:: --private
+
     Use private IP address
 
-:option:`--address-type` <address-type>
+.. option:: --address-type <address-type>
+
     Use other IP address (public, private, etc)
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server suspend
@@ -483,7 +559,8 @@ Suspend server
     os server suspend
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server unlock
@@ -496,7 +573,8 @@ Unlock server
     os server unlock
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server unpause
@@ -509,7 +587,8 @@ Unpause server
     os server unpause
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server unrescue
@@ -522,7 +601,8 @@ Restore server from rescue mode
     os server unrescue
         <server>
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)
 
 server unset
@@ -537,8 +617,10 @@ Unset server properties
         [--property <key>] ...
         <server>
 
-:option:`--property` <key>
+.. option:: --property <key>
+
     Property key to remove from server (repeat to set multiple values)
 
-:option:`<server>`
+.. describe:: <server>
+
     Server (name or ID)