Improved the docopt docs with example, etc.

aparnapatil · aparnapatil · commit 3632cca7650a · 2014-04-09T03:08:33.000-05:00
diff --git a/SoftLayer/CLI/modules/iscsi.py b/SoftLayer/CLI/modules/iscsi.py
@@ -1,29 +1,29 @@
 """
 usage: sl iscsi [<command>] [<args>...] [options]
 
-Manage iSCSI targets
+Manage, order, delete iSCSI targets
 
 The available commands are:
-  cancel  Cancel iSCSI target
-  create  Create iSCSI target
-  detail  Output details about iSCSI
-  list    List iSCSI targets
+  cancel  Cancel an existing iSCSI target
+  create  Order and create an iSCSI target
+  detail  Output details about an iSCSI
+  list    List iSCSI targets on the account
 
-For several commands, <identifier> will be asked for. This can be the id
-for iSCSI.
+For several commands, <identifier> will be asked for. This will be the id
+for iSCSI target.
 """
 from SoftLayer.CLI import (CLIRunnable, Table, no_going_back, FormattedItem)
 from SoftLayer.CLI.helpers import (
     CLIAbort, ArgumentError, NestedDict, blank, resolve_id, KeyValueTable)
 from SoftLayer import ISCSIManager
 
 
-class ListISCSI(CLIRunnable):
+class ListISCSIs(CLIRunnable):
 
     """
-    usage: sl iscsi list [options]
+usage: sl iscsi list [options]
 
-List iSCSI accounts
+List iSCSI targets
 """
     action = 'list'
 
@@ -60,14 +60,19 @@ def execute(self, args):
 class CreateISCSI(CLIRunnable):
 
     """
-    usage: sl iscsi create [options]
+usage: sl iscsi create [options]
 
-    Order/create an iSCSI storage.
+Orders and creates an iSCSI target.
 
-    Required:
-     -s, --size=SIZE       Size of the iSCSI volume to create
-     -d, --datacenter=DC   Datacenter shortname (sng01, dal05, ...)
-     """
+Examples:
+    sl iscsi create --size=1 --datacenter=dal05
+    sl iscsi create --size 1 -d dal05
+    sl iscsi create -s 1 -d dal05
+
+Required:
+  -s, --size=SIZE       Size of the iSCSI volume to create
+  -d, --datacenter=DC   Datacenter shortname (sng01, dal05, ...)
+"""
     action = 'create'
     options = ['confirm']
     required_params = ['--size', '--datacenter']
@@ -83,9 +88,9 @@ def _parse_create_args(self, args):
             ISCSIManager.create_iscsi.
         :param dict args: CLI arguments
         """
-        size = int(args['--size'])
-        location = str(args['--datacenter'])
-        return size, location
+        size = args['--size']
+        location = args['--datacenter']
+        return int(size), str(location)
 
     def _validate_create_args(self, args):
         """ Raises an ArgumentError if the given arguments are not valid """
@@ -100,13 +105,17 @@ class CancelISCSI(CLIRunnable):
     """
 usage: sl iscsi cancel <identifier> [options]
 
-Cancel iSCSI Storage
+Cancel existing iSCSI
 
-options :
---immediate    Cancels the iSCSI immediately (instead of on the billing
-             anniversary)
---reason=REASON    An optional cancellation reason.
+Examples:
+    sl iscsi cancel 12345
+    sl iscsi cancel 12345 --immediate
+    sl iscsi cancel 12345 --immediate --reason='no longer needed'
 
+options :
+  --immediate    Cancels the iSCSI immediately (instead of on the billing
+                    anniversary)
+  --reason=REASON    An optional reason for cancellation.
 """
     action = 'cancel'
     options = ['confirm']
@@ -132,12 +141,14 @@ class ISCSIDetails(CLIRunnable):
     """
 usage: sl iscsi detail [--password] <identifier> [options]
 
-Get details for a iSCSI
-
-Options:
-  --password  Show password
+Get details for an iSCSI
 
+Examples:
+    sl iscsi detail 12345
+    sl iscsi detail 12345 --password
 
+Options:
+  --password  Show credentials to access the iSCSI target
 """
     action = 'detail'
 
diff --git a/SoftLayer/CLI/modules/snapshot.py b/SoftLayer/CLI/modules/snapshot.py
@@ -1,15 +1,17 @@
 """
 usage: sl snapshot [<command>] [<args>...] [options]
 
-Manage iSCSI snapshots
+Manage, order, delete iSCSI snapshots
 
 The available commands are:
-  create          Create snapshot of iSCSI
-  create_space    Orders space for snapshots
-  delete          Delete iSCSI snapshot
+  cancel          Cancel an iSCSI snapshot
+  create          Create a snapshot of given iSCSI volume
+  create-space    Orders space for storing snapshots
   list            List snpshots of given iSCSI
-  restore_volume  Restores volume from existing snapshot
+  restore-volume  Restores volume from existing snapshot
 
+For several commands <identifier> will be asked for.This can be the id
+of iSCSI volume or iSCSI snapshot.
 """
 from SoftLayer.CLI import (CLIRunnable, Table)
 from SoftLayer.CLI.helpers import (
@@ -18,15 +20,19 @@
 from SoftLayer import ISCSIManager
 
 
-class ISCSICreateSnapshot(CLIRunnable):
+class CreateSnapshot(CLIRunnable):
 
     """
 usage: sl snapshot create <identifier> [options]
 
-create an iSCSI snapshot.
+Create a snapshot of the iSCSI volume.
+
+Examples:
+    sl snapshot create 123456 --note='Backup'
+    sl snapshot create 123456
 
 Options:
-  --notes=NOTE    An optional note
+  --notes=NOTE    An optional snapshot's note
 
 """
     action = 'create'
@@ -41,18 +47,21 @@ def execute(self, args):
         iscsi_mgr.create_snapshot(iscsi_id, notes)
 
 
-class CreateIscsiSpace(CLIRunnable):
+class CreateSnapshotSpace(CLIRunnable):
 
     """
-usage: sl snapshot create_space <identifier> [options]
+usage: sl snapshot create-space <identifier> [options]
+
+Orders snapshot space for given iSCSI.
 
-Orders iSCSI snapshot space.
+Examples:
+    sl snapshot create-space 123456 --capacity=20
 
 Required :
-  --capacity=Capacity Snapshot Capacity
+  --capacity=CAPACITY Size of snapshot space to create
 """
 
-    action = 'create_space'
+    action = 'create-space'
     required_params = ['--capacity']
 
     def execute(self, args):
@@ -69,15 +78,15 @@ def execute(self, args):
         iscsi_mgr.create_snapshot_space(iscsi_id, capacity)
 
 
-class ISCSIDeleteSnapshot(CLIRunnable):
+class CancelSnapshot(CLIRunnable):
 
     """
-usage: sl snapshot delete <identifier> [options]
+usage: sl snapshot cancel <identifier> [options]
 
-Delete iSCSI snapshot.
+Cancel/Delete iSCSI snapshot.
 
 """
-    action = 'delete'
+    action = 'cancel'
 
     def execute(self, args):
         iscsi_mgr = ISCSIManager(self.client)
@@ -91,12 +100,12 @@ def execute(self, args):
 class RestoreVolumeFromSnapshot(CLIRunnable):
 
     """
-usage: sl snapshot restore_volume <volume_identifier> <snapshot_identifier>
+usage: sl snapshot restore-volume <volume_identifier> <snapshot_identifier>
 
 restores volume from existing snapshot.
 
 """
-    action = 'restore_volume'
+    action = 'restore-volume'
 
     def execute(self, args):
         iscsi_mgr = ISCSIManager(self.client)
@@ -109,7 +118,7 @@ def execute(self, args):
         iscsi_mgr.restore_from_snapshot(volume_id, snapshot_id)
 
 
-class ListISCSISnapshots(CLIRunnable):
+class ListSnapshots(CLIRunnable):
 
     """
 usage: sl snapshot list <identifier>
