From f9359139096241fd5506ce3b9ace92098690e57c Mon Sep 17 00:00:00 2001 From: allmightyspiff Date: Fri, 24 Jan 2020 18:00:09 -0600 Subject: [PATCH 1/3] #1215 adding in a bunch of CLI documentation --- docs/cli/block.rst | 112 +++++++++++++++++++++++++++++++++++++++++ docs/cli/call_api.rst | 9 ---- docs/cli/cdn.rst | 2 +- docs/cli/commands.rst | 17 +++++++ docs/cli/config.rst | 7 ++- docs/cli/dedicated.rst | 33 ++++++++++++ docs/cli/dns.rst | 41 +++++++++++++++ docs/cli/file.rst | 104 ++++++++++++++++++++++++++++++++++++++ docs/cli/firewall.rst | 24 +++++++++ docs/cli/global_ip.rst | 24 +++++++++ docs/cli/hardware.rst | 2 +- docs/dev/cli.rst | 35 +++++++++++++ 12 files changed, 398 insertions(+), 12 deletions(-) create mode 100644 docs/cli/block.rst delete mode 100644 docs/cli/call_api.rst create mode 100644 docs/cli/commands.rst create mode 100644 docs/cli/dedicated.rst create mode 100644 docs/cli/dns.rst create mode 100644 docs/cli/file.rst create mode 100644 docs/cli/firewall.rst create mode 100644 docs/cli/global_ip.rst diff --git a/docs/cli/block.rst b/docs/cli/block.rst new file mode 100644 index 000000000..5ca8140b7 --- /dev/null +++ b/docs/cli/block.rst @@ -0,0 +1,112 @@ +.. _cli_block: + +Block Commands +============== + +.. click:: SoftLayer.CLI.block.access.authorize:cli + :prog: block access-authorize + :show-nested: + +.. click:: SoftLayer.CLI.block.access.list:cli + :prog: block access-list + :show-nested: + +.. click:: SoftLayer.CLI.block.access.revoke:cli + :prog: block access-revoke + :show-nested: + +.. click:: SoftLayer.CLI.block.access.password:cli + :prog: block access-password + :show-nested: + +.. click:: SoftLayer.CLI.block.replication.failback:cli + :prog: block replica-failback + :show-nested: + +.. click:: SoftLayer.CLI.block.replication.failover:cli + :prog: block replica-failover + :show-nested: + +.. click:: SoftLayer.CLI.block.replication.order:cli + :prog: block replica-order + :show-nested: + +.. click:: SoftLayer.CLI.block.replication.partners:cli + :prog: block replica-partners + :show-nested: + +.. click:: SoftLayer.CLI.block.replication.locations:cli + :prog: block replica-locations + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.cancel:cli + :prog: block snapshot-cancel + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.create:cli + :prog: block snapshot-create + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.delete:cli + :prog: block snapshot-delete + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.disable:cli + :prog: block snapshot-disable + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.enable:cli + :prog: block snapshot-enable + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.schedule_list:cli + :prog: block snapshot-schedule-list + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.list:cli + :prog: block snapshot-list + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.order:cli + :prog: block snapshot-order + :show-nested: + +.. click:: SoftLayer.CLI.block.snapshot.restore:cli + :prog: block snapshot-restore + :show-nested: + +.. click:: SoftLayer.CLI.block.cancel:cli + :prog: block volume-cancel + :show-nested: + +.. click:: SoftLayer.CLI.block.count:cli + :prog: block volume-count + :show-nested: + +.. click:: SoftLayer.CLI.block.detail:cli + :prog: block volume-detail + :show-nested: + +.. click:: SoftLayer.CLI.block.duplicate:cli + :prog: block volume-duplicate + :show-nested: + +.. click:: SoftLayer.CLI.block.list:cli + :prog: block volume-list + :show-nested: + +.. click:: SoftLayer.CLI.block.modify:cli + :prog: block volume-modify + :show-nested: + +.. click:: SoftLayer.CLI.block.order:cli + :prog: block volume-order + :show-nested: + +.. click:: SoftLayer.CLI.block.lun:cli + :prog: block volume-set-lun-id + :show-nested: + +.. click:: SoftLayer.CLI.block.limit:cli + :prog: block volume-limits + :show-nested: diff --git a/docs/cli/call_api.rst b/docs/cli/call_api.rst deleted file mode 100644 index e309f16eb..000000000 --- a/docs/cli/call_api.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _cli_call_api: - -Call API -======== - - -.. click:: SoftLayer.CLI.call_api:cli - :prog: call-api - :show-nested: diff --git a/docs/cli/cdn.rst b/docs/cli/cdn.rst index fce54f731..e334cd6f3 100644 --- a/docs/cli/cdn.rst +++ b/docs/cli/cdn.rst @@ -1,7 +1,7 @@ .. _cli_cdn: Interacting with CDN -============================== +===================== .. click:: SoftLayer.CLI.cdn.detail:cli diff --git a/docs/cli/commands.rst b/docs/cli/commands.rst new file mode 100644 index 000000000..e29b1d0e8 --- /dev/null +++ b/docs/cli/commands.rst @@ -0,0 +1,17 @@ +.. _cli_commands: + +Call API +======== + + +.. click:: SoftLayer.CLI.call_api:cli + :prog: call-api + :show-nested: + + +Shell +===== + +.. click:: SoftLayer.shell.core:cli + :prog: shell + :show-nested: diff --git a/docs/cli/config.rst b/docs/cli/config.rst index b49e5d5ad..dd8bf1a93 100644 --- a/docs/cli/config.rst +++ b/docs/cli/config.rst @@ -1,7 +1,7 @@ .. _cli_config: Config -======== +====== `Creating an IBMID apikey `_ `IBMid for services `_ @@ -16,3 +16,8 @@ Config .. click:: SoftLayer.CLI.config.show:cli :prog: config show :show-nested: + + +.. click:: SoftLayer.CLI.config.setup:cli + :prog: setup + :show-nested: diff --git a/docs/cli/dedicated.rst b/docs/cli/dedicated.rst new file mode 100644 index 000000000..ba11fb536 --- /dev/null +++ b/docs/cli/dedicated.rst @@ -0,0 +1,33 @@ +.. _cli_dedicated: + +Dedicated Host Commands +======================= + + +.. click:: SoftLayer.CLI.dedicatedhost.list:cli + :prog: dedicatedhost list + :show-nested: + +.. click:: SoftLayer.CLI.dedicatedhost.create:cli + :prog: dedicatedhost create + :show-nested: + +.. click:: SoftLayer.CLI.dedicatedhost.create_options:cli + :prog: dedicatedhost create-options + :show-nested: + +.. click:: SoftLayer.CLI.dedicatedhost.detail:cli + :prog: dedicatedhost detail + :show-nested: + +.. click:: SoftLayer.CLI.dedicatedhost.cancel:cli + :prog: dedicatedhost cancel + :show-nested: + +.. click:: SoftLayer.CLI.dedicatedhost.cancel_guests:cli + :prog: dedicatedhost cancel-guests + :show-nested: + +.. click:: SoftLayer.CLI.dedicatedhost.list_guests:cli + :prog: dedicatedhost list-guests + :show-nested: diff --git a/docs/cli/dns.rst b/docs/cli/dns.rst new file mode 100644 index 000000000..c62bb7ada --- /dev/null +++ b/docs/cli/dns.rst @@ -0,0 +1,41 @@ +.. _cli_dns: + +DNS Management +============== + + +.. click:: SoftLayer.CLI.dns.zone_import:cli + :prog: dns import + :show-nested: + +.. click:: SoftLayer.CLI.dns.record_add:cli + :prog: dns record-add + :show-nested: + +.. click:: SoftLayer.CLI.dns.record_edit:cli + :prog: dns record-edit + :show-nested: + +.. click:: SoftLayer.CLI.dns.record_list:cli + :prog: dns record-list + :show-nested: + +.. click:: SoftLayer.CLI.dns.record_remove:cli + :prog: dns record-remove + :show-nested: + +.. click:: SoftLayer.CLI.dns.zone_create:cli + :prog: dns zone-create + :show-nested: + +.. click:: SoftLayer.CLI.dns.zone_delete:cli + :prog: dns zone-delete + :show-nested: + +.. click:: SoftLayer.CLI.dns.zone_list:cli + :prog: dns zone-list + :show-nested: + +.. click:: SoftLayer.CLI.dns.zone_print:cli + :prog: dns zone-print + :show-nested: diff --git a/docs/cli/file.rst b/docs/cli/file.rst new file mode 100644 index 000000000..ad01b0337 --- /dev/null +++ b/docs/cli/file.rst @@ -0,0 +1,104 @@ +.. _cli_file: + +File Commands +============= + +.. click:: SoftLayer.CLI.file.access.authorize:cli + :prog: file access-authorize + :show-nested: + +.. click:: SoftLayer.CLI.file.access.list:cli + :prog: file access-list + :show-nested: + +.. click:: SoftLayer.CLI.file.access.revoke:cli + :prog: file access-revoke + :show-nested: + +.. click:: SoftLayer.CLI.file.replication.failback:cli + :prog: file replica-failback + :show-nested: + +.. click:: SoftLayer.CLI.file.replication.failover:cli + :prog: file replica-failover + :show-nested: + +.. click:: SoftLayer.CLI.file.replication.order:cli + :prog: file replica-order + :show-nested: + +.. click:: SoftLayer.CLI.file.replication.partners:cli + :prog: file replica-partners + :show-nested: + +.. click:: SoftLayer.CLI.file.replication.locations:cli + :prog: file replica-locations + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.cancel:cli + :prog: file snapshot-cancel + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.create:cli + :prog: file snapshot-create + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.delete:cli + :prog: file snapshot-delete + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.disable:cli + :prog: file snapshot-disable + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.enable:cli + :prog: file snapshot-enable + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.list:cli + :prog: file snapshot-list + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.order:cli + :prog: file snapshot-order + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.restore:cli + :prog: file snapshot-restore + :show-nested: + +.. click:: SoftLayer.CLI.file.cancel:cli + :prog: file volume-cancel + :show-nested: + +.. click:: SoftLayer.CLI.file.count:cli + :prog: file volume-count + :show-nested: + +.. click:: SoftLayer.CLI.file.detail:cli + :prog: file volume-detail + :show-nested: + +.. click:: SoftLayer.CLI.file.duplicate:cli + :prog: file volume-duplicate + :show-nested: + +.. click:: SoftLayer.CLI.file.list:cli + :prog: file volume-list + :show-nested: + +.. click:: SoftLayer.CLI.file.modify:cli + :prog: file volume-modify + :show-nested: + +.. click:: SoftLayer.CLI.file.order:cli + :prog: file volume-order + :show-nested: + +.. click:: SoftLayer.CLI.file.limit:cli + :prog: file volume-limits + :show-nested: + +.. click:: SoftLayer.CLI.file.snapshot.schedule_list:cli + :prog: file snapshot-schedule-list + :show-nested: diff --git a/docs/cli/firewall.rst b/docs/cli/firewall.rst new file mode 100644 index 000000000..bae1c99d7 --- /dev/null +++ b/docs/cli/firewall.rst @@ -0,0 +1,24 @@ +.. _cli_firewall: + +Firewall Management +=================== + +.. click:: SoftLayer.CLI.firewall.add:cli + :prog: firewall add + :show-nested: + +.. click:: SoftLayer.CLI.firewall.cancel:cli + :prog: firewall cancel + :show-nested: + +.. click:: SoftLayer.CLI.firewall.detail:cli + :prog: firewall detail + :show-nested: + +.. click:: SoftLayer.CLI.firewall.edit:cli + :prog: firewall edit + :show-nested: + +.. click:: SoftLayer.CLI.firewall.list:cli + :prog: firewall list + :show-nested: diff --git a/docs/cli/global_ip.rst b/docs/cli/global_ip.rst new file mode 100644 index 000000000..0e07b4a44 --- /dev/null +++ b/docs/cli/global_ip.rst @@ -0,0 +1,24 @@ +.. _cli_global_ip: + +Global IP Addresses +=================== + +.. click:: SoftLayer.CLI.globalip.assign:cli + :prog: globalip assign + :show-nested: + +.. click:: SoftLayer.CLI.globalip.cancel:cli + :prog: globalip cancel + :show-nested: + +.. click:: SoftLayer.CLI.globalip.create:cli + :prog: globalip create + :show-nested: + +.. click:: SoftLayer.CLI.globalip.list:cli + :prog: globalip list + :show-nested: + +.. click:: SoftLayer.CLI.globalip.unassign:cli + :prog: globalip unassign + :show-nested: diff --git a/docs/cli/hardware.rst b/docs/cli/hardware.rst index 08fc273d6..c11402bd3 100644 --- a/docs/cli/hardware.rst +++ b/docs/cli/hardware.rst @@ -94,6 +94,6 @@ This function updates the firmware of a server. If already at the latest version :prog: hw ready :show-nested: -.. click:: SoftLayer.CLI.hardware.dns-sync:cli +.. click:: SoftLayer.CLI.hardware.dns:cli :prog: hw dns-sync :show-nested: diff --git a/docs/dev/cli.rst b/docs/dev/cli.rst index 3962181ac..c1922b268 100644 --- a/docs/dev/cli.rst +++ b/docs/dev/cli.rst @@ -133,3 +133,38 @@ When a confirmation fails, you probably want to stop execution and give a non-ze :: raise CLIAbort("Aborting. Failed confirmation") + + + +Documenting Commands +-------------------- + +All commands should be documented, luckily there is a sphinx module that makes this pretty easy. + +If you were adding a summary command to `slcli account` you would find the documentation in `docs/cli/account.rst` and you would just need to add this for your command + +``` +.. click:: SoftLayer.CLI.account.summary:cli + :prog: account summary + :show-nested: +``` + + +The following REGEX can take the route entry and turn it into a document entry. + +``` +s/^\('([a-z]*):([a-z-]*)', '([a-zA-Z\.:_]*)'\),$/.. click:: $3\n :prog: $1 $2\n :show-nested:\n/ +``` + +FIND: +``` +^\('([a-z]*):([a-z-]*)', '([a-zA-Z\.:_]*)'\),$ +``` + +REPLACE: +``` +.. click:: $3 + :prog: $1 $2 + :show-nested: + +``` From 906f11baa585f840f72c70c1a84ed2f60a63f059 Mon Sep 17 00:00:00 2001 From: allmightyspiff Date: Fri, 24 Jan 2020 18:03:01 -0600 Subject: [PATCH 2/3] adding comment about trying to use sphinx-click to auto document everything and how that didn't work --- docs/dev/cli.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/dev/cli.rst b/docs/dev/cli.rst index c1922b268..31853174e 100644 --- a/docs/dev/cli.rst +++ b/docs/dev/cli.rst @@ -168,3 +168,7 @@ REPLACE: :show-nested: ``` + + +I tried to get sphinx-click to auto document the ENTIRE slcli, but the results were all on one page, and required a few changes to sphinx-click itself to work. This is due to the fact that most commands in SLCLI use the function name "cli", and some hacks would have to be put inplace to use the path name instead. + From b7416ff5f93766965ad17cf3b6a9f82b545cb5b6 Mon Sep 17 00:00:00 2001 From: allmightyspiff Date: Wed, 29 Jan 2020 15:43:00 -0600 Subject: [PATCH 3/3] #1215 added docs for every CLI command. --- SoftLayer/CLI/metadata.py | 17 +-- SoftLayer/CLI/user/create.py | 9 +- SoftLayer/CLI/user/delete.py | 1 + SoftLayer/CLI/user/edit_details.py | 5 +- SoftLayer/CLI/user/edit_permissions.py | 1 + SoftLayer/managers/autoscale.py | 2 + docs/cli.rst | 169 +++++++++++++------------ docs/cli/commands.rst | 12 ++ docs/cli/image.rst | 28 ++++ docs/cli/loadbal.rst | 2 +- docs/cli/object_storage.rst | 30 +++++ docs/cli/rwhois.rst | 12 ++ docs/cli/security_groups.rst | 56 ++++++++ docs/cli/sshkey.rst | 24 ++++ docs/cli/ssl.rst | 25 ++++ docs/cli/subnet.rst | 24 ++++ docs/cli/tickets.rst | 40 ++++++ docs/cli/users.rst | 103 +++------------ docs/cli/vlan.rst | 12 ++ docs/cli/vs.rst | 167 ++++++++++++------------ docs/cli_directory.rst | 10 ++ docs/dev/cli.rst | 51 +++++--- docs/index.rst | 1 + 23 files changed, 520 insertions(+), 281 deletions(-) create mode 100644 docs/cli/image.rst create mode 100644 docs/cli/object_storage.rst create mode 100644 docs/cli/rwhois.rst create mode 100644 docs/cli/security_groups.rst create mode 100644 docs/cli/sshkey.rst create mode 100644 docs/cli/ssl.rst create mode 100644 docs/cli/subnet.rst create mode 100644 docs/cli/tickets.rst create mode 100644 docs/cli/vlan.rst create mode 100644 docs/cli_directory.rst diff --git a/SoftLayer/CLI/metadata.py b/SoftLayer/CLI/metadata.py index 3cc3e384d..26d6f2d48 100644 --- a/SoftLayer/CLI/metadata.py +++ b/SoftLayer/CLI/metadata.py @@ -28,16 +28,13 @@ 'ip': 'primary_ip', } -HELP = """Find details about this machine - -\b -PROP Choices -%s -\b -Examples : -%s -""" % ('*' + '\n*'.join(META_CHOICES), - 'slcli metadata ' + '\nslcli metadata '.join(META_CHOICES)) +HELP = """Find details about the machine making these API calls. + +.. csv-table:: Choices + + {choices} + +""".format(choices="\n ".join(META_CHOICES)) @click.command(help=HELP, diff --git a/SoftLayer/CLI/user/create.py b/SoftLayer/CLI/user/create.py index 6ab19884a..ccfe55955 100644 --- a/SoftLayer/CLI/user/create.py +++ b/SoftLayer/CLI/user/create.py @@ -34,10 +34,13 @@ def cli(env, username, email, password, from_user, template, api_key): """Creates a user Users. - :Example: slcli user create my@email.com -e my@email.com -p generate -a - -t '{"firstName": "Test", "lastName": "Testerson"}' - Remember to set the permissions and access for this new user. + + Example:: + + slcli user create my@email.com -e my@email.com -p generate -a + -t '{"firstName": "Test", "lastName": "Testerson"}' + """ mgr = SoftLayer.UserManager(env.client) diff --git a/SoftLayer/CLI/user/delete.py b/SoftLayer/CLI/user/delete.py index 409c94661..9c00af754 100644 --- a/SoftLayer/CLI/user/delete.py +++ b/SoftLayer/CLI/user/delete.py @@ -17,6 +17,7 @@ def cli(env, identifier): and will eventually be fully removed from the account by an automated internal process. Example: slcli user delete userId + """ mgr = SoftLayer.UserManager(env.client) diff --git a/SoftLayer/CLI/user/edit_details.py b/SoftLayer/CLI/user/edit_details.py index 024421ed0..5e88427a4 100644 --- a/SoftLayer/CLI/user/edit_details.py +++ b/SoftLayer/CLI/user/edit_details.py @@ -22,7 +22,10 @@ def cli(env, user, template): JSON strings should be enclosed in '' and each item should be enclosed in "" - :Example: slcli user edit-details testUser -t '{"firstName": "Test", "lastName": "Testerson"}' + Example:: + + slcli user edit-details testUser -t '{"firstName": "Test", "lastName": "Testerson"}' + """ mgr = SoftLayer.UserManager(env.client) user_id = helpers.resolve_id(mgr.resolve_ids, user, 'username') diff --git a/SoftLayer/CLI/user/edit_permissions.py b/SoftLayer/CLI/user/edit_permissions.py index e86ee256a..64791d312 100644 --- a/SoftLayer/CLI/user/edit_permissions.py +++ b/SoftLayer/CLI/user/edit_permissions.py @@ -21,6 +21,7 @@ @environment.pass_env def cli(env, identifier, enable, permission, from_user): """Enable or Disable specific permissions.""" + mgr = SoftLayer.UserManager(env.client) user_id = helpers.resolve_id(mgr.resolve_ids, identifier, 'username') result = False diff --git a/SoftLayer/managers/autoscale.py b/SoftLayer/managers/autoscale.py index 40d7ebe80..78fa18e31 100644 --- a/SoftLayer/managers/autoscale.py +++ b/SoftLayer/managers/autoscale.py @@ -99,6 +99,7 @@ def get_virtual_guests(self, identifier, mask=None): :param identifier: SoftLayer_Scale_Group Id :param mask: optional SoftLayer_Scale_Member objectMask + .. _SoftLayer_Scale_Group::getVirtualGuestMembers(): https://sldn.softlayer.com/reference/services/SoftLayer_Scale_Group/getVirtualGuestMembers/ """ @@ -109,6 +110,7 @@ def edit(self, identifier, template): :param identifier: SoftLayer_Scale_Group id :param template: `SoftLayer_Scale_Group`_ + .. _SoftLayer_Scale_Group::editObject(): https://sldn.softlayer.com/reference/services/SoftLayer_Scale_Group/editObject/ .. _SoftLayer_Scale_Group: https://sldn.softlayer.com/reference/datatypes/SoftLayer_Scale_Group/ diff --git a/docs/cli.rst b/docs/cli.rst index 7b09fdc17..dc82da29f 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -9,43 +9,39 @@ SoftLayer API bindings for python and how to efficiently make API calls. See the :ref:`usage-examples` section to see how to discover all of the functionality not fully documented here. -.. toctree:: - :maxdepth: 2 - :glob: - - cli/* - .. _config_setup: Configuration Setup ------------------- To update the configuration, you can use `slcli setup`. + :: - $ slcli setup - Username []: username - API Key or Password []: - Endpoint (public|private|custom): public - :..............:..................................................................: - : Name : Value : - :..............:..................................................................: - : Username : username : - : API Key : oyVmeipYQCNrjVS4rF9bHWV7D75S6pa1fghFl384v7mwRCbHTfuJ8qRORIqoVnha : - : Endpoint URL : https://api.softlayer.com/xmlrpc/v3.1/ : - :..............:..................................................................: - Are you sure you want to write settings to "/home/me/.softlayer"? [y/N]: y + $ slcli setup + Username []: username + API Key or Password []: + Endpoint (public|private|custom): public + :..............:..................................................................: + : Name : Value : + :..............:..................................................................: + : Username : username : + : API Key : oyVmeipYQCNrjVS4rF9bHWV7D75S6pa1fghFl384v7mwRCbHTfuJ8qRORIqoVnha : + : Endpoint URL : https://api.softlayer.com/xmlrpc/v3.1/ : + :..............:..................................................................: + Are you sure you want to write settings to "/home/me/.softlayer"? [y/N]: y To check the configuration, you can use `slcli config show`. + :: - $ slcli config show - :..............:..................................................................: - : Name : Value : - :..............:..................................................................: - : Username : username : - : API Key : oyVmeipYQCNrjVS4rF9bHWV7D75S6pa1fghFl384v7mwRCbHTfuJ8qRORIqoVnha : - : Endpoint URL : https://api.softlayer.com/xmlrpc/v3.1/ : - :..............:..................................................................: + $ slcli config show + :..............:..................................................................: + : Name : Value : + :..............:..................................................................: + : Username : username : + : API Key : oyVmeipYQCNrjVS4rF9bHWV7D75S6pa1fghFl384v7mwRCbHTfuJ8qRORIqoVnha : + : Endpoint URL : https://api.softlayer.com/xmlrpc/v3.1/ : + :..............:..................................................................: If you are using an account created from the https://cloud.ibm.com portal, your username will be literally `apikey`, and use the key provided. `How to create an IBM apikey `_ @@ -57,6 +53,8 @@ To see more about the config file format, see :ref:`config_file`. Usage Examples -------------- To discover the available commands, simply type `slcli`. + + :: $ slcli @@ -112,71 +110,76 @@ To discover the available commands, simply type `slcli`. As you can see, there are a number of commands/sections. To look at the list of subcommands for virtual servers type `slcli vs`. For example: -:: - $ slcli vs - Usage: slcli vs [OPTIONS] COMMAND [ARGS]... - - Virtual Servers. - - Options: - --help Show this message and exit. - - Commands: - cancel Cancel virtual servers. - capture Capture SoftLayer image. - create Order/create virtual servers. - create-options Virtual server order options. - credentials List virtual server credentials. - detail Get details for a virtual server. - dns-sync Sync DNS records. - edit Edit a virtual server's details. - list List virtual servers. - network Manage network settings. - pause Pauses an active virtual server. - power_off Power off an active virtual server. - power_on Power on a virtual server. - ready Check if a virtual server is ready. - reboot Reboot an active virtual server. - reload Reload operating system on a virtual server. - rescue Reboot into a rescue image. - resume Resumes a paused virtual server. - upgrade Upgrade a virtual server. - -Finally, we can make an actual call. Let's list out the virtual servers on our -account by using `slcli vs list`. :: - $ slcli vs list - :.........:............:....................:.......:........:................:..............:....................: - : id : datacenter : host : cores : memory : primary_ip : backend_ip : active_transaction : - :.........:............:....................:.......:........:................:..............:....................: - : 1234567 : sjc01 : test.example.com : 4 : 4G : 12.34.56 : 65.43.21 : - : - :.........:............:....................:.......:........:................:..............:....................: + $ slcli vs + Usage: slcli vs [OPTIONS] COMMAND [ARGS]... + + Virtual Servers. + + Options: + --help Show this message and exit. + + Commands: + cancel Cancel virtual servers. + capture Capture SoftLayer image. + create Order/create virtual servers. + create-options Virtual server order options. + credentials List virtual server credentials. + detail Get details for a virtual server. + dns-sync Sync DNS records. + edit Edit a virtual server's details. + list List virtual servers. + network Manage network settings. + pause Pauses an active virtual server. + power_off Power off an active virtual server. + power_on Power on a virtual server. + ready Check if a virtual server is ready. + reboot Reboot an active virtual server. + reload Reload operating system on a virtual server. + rescue Reboot into a rescue image. + resume Resumes a paused virtual server. + upgrade Upgrade a virtual server. + + +Finally, we can make an actual call. Let's list out the virtual servers on our account by using `slcli vs list`. + + +Example:: + + $ slcli vs list + :.........:............:....................:.......:........:................:..............:....................: + : id : datacenter : host : cores : memory : primary_ip : backend_ip : active_transaction : + :.........:............:....................:.......:........:................:..............:....................: + : 1234567 : sjc01 : test.example.com : 4 : 4G : 12.34.56 : 65.43.21 : - : + :.........:............:....................:.......:........:................:..............:....................: Most commands will take in additional options/arguments. To see all available actions, use `--help`. + + :: - $ slcli vs list --help - Usage: slcli vs list [OPTIONS] - - List virtual servers. - - Options: - --sortby [guid|hostname|primary_ip|backend_ip|datacenter] - Column to sort by - -c, --cpu INTEGER Number of CPU cores - -D, --domain TEXT Domain portion of the FQDN - -d, --datacenter TEXT Datacenter shortname - -H, --hostname TEXT Host portion of the FQDN - -m, --memory INTEGER Memory in mebibytes - -n, --network TEXT Network port speed in Mbps - --hourly Show only hourly instances - --monthly Show only monthly instances - --tags TEXT Show instances that have one of these comma- - separated tags - --help Show this message and exit. + $ slcli vs list --help + Usage: slcli vs list [OPTIONS] + + List virtual servers. + + Options: + --sortby [guid|hostname|primary_ip|backend_ip|datacenter] + Column to sort by + -c, --cpu INTEGER Number of CPU cores + -D, --domain TEXT Domain portion of the FQDN + -d, --datacenter TEXT Datacenter shortname + -H, --hostname TEXT Host portion of the FQDN + -m, --memory INTEGER Memory in mebibytes + -n, --network TEXT Network port speed in Mbps + --hourly Show only hourly instances + --monthly Show only monthly instances + --tags TEXT Show instances that have one of these comma- + separated tags + --help Show this message and exit. diff --git a/docs/cli/commands.rst b/docs/cli/commands.rst index e29b1d0e8..a577adcdb 100644 --- a/docs/cli/commands.rst +++ b/docs/cli/commands.rst @@ -15,3 +15,15 @@ Shell .. click:: SoftLayer.shell.core:cli :prog: shell :show-nested: + + + +MetaData +======== + +Used to retrieve information about the server making the API call. +Can be called with an un-authenticated API call. + +.. click:: SoftLayer.CLI.metadata:cli + :prog: metadata + :show-nested: diff --git a/docs/cli/image.rst b/docs/cli/image.rst new file mode 100644 index 000000000..771abd16c --- /dev/null +++ b/docs/cli/image.rst @@ -0,0 +1,28 @@ +.. _cli_image: + +Disk Image Commands +=================== + +.. click:: SoftLayer.CLI.image.delete:cli + :prog: image delete + :show-nested: + +.. click:: SoftLayer.CLI.image.detail:cli + :prog: image detail + :show-nested: + +.. click:: SoftLayer.CLI.image.edit:cli + :prog: image edit + :show-nested: + +.. click:: SoftLayer.CLI.image.list:cli + :prog: image list + :show-nested: + +.. click:: SoftLayer.CLI.image.import:cli + :prog: image import + :show-nested: + +.. click:: SoftLayer.CLI.image.export:cli + :prog: image export + :show-nested: diff --git a/docs/cli/loadbal.rst b/docs/cli/loadbal.rst index b1a6a0dcc..cec4200fd 100644 --- a/docs/cli/loadbal.rst +++ b/docs/cli/loadbal.rst @@ -23,7 +23,7 @@ LBaaS Commands :prog: loadbal member-add :show-nested: .. click:: SoftLayer.CLI.loadbal.members:remove - :prog: loadbal member-remote + :prog: loadbal member-remove :show-nested: .. click:: SoftLayer.CLI.loadbal.pools:add :prog: loadbal pool-add diff --git a/docs/cli/object_storage.rst b/docs/cli/object_storage.rst new file mode 100644 index 000000000..43bf03bb8 --- /dev/null +++ b/docs/cli/object_storage.rst @@ -0,0 +1,30 @@ +.. _cli_object_storage: + +Object Storage Commands +======================= + + +.. click:: SoftLayer.CLI.object_storage.list_accounts:cli + :prog: object-storage accounts + :show-nested: + +.. click:: SoftLayer.CLI.object_storage.list_endpoints:cli + :prog: object-storage endpoints + :show-nested: + +.. click:: SoftLayer.CLI.object_storage.credential.list:cli + :prog: object-storage credential list + :show-nested: + + +.. click:: SoftLayer.CLI.object_storage.credential.limit:cli + :prog: object-storage credential limit + :show-nested: + +.. click:: SoftLayer.CLI.object_storage.credential.delete:cli + :prog: object-storage credential delete + :show-nested: + +.. click:: SoftLayer.CLI.object_storage.credential.create:cli + :prog: object-storage credential create + :show-nested: diff --git a/docs/cli/rwhois.rst b/docs/cli/rwhois.rst new file mode 100644 index 000000000..10d2004c9 --- /dev/null +++ b/docs/cli/rwhois.rst @@ -0,0 +1,12 @@ +.. _cli_rwhois: + +Reverse Whois Commands +====================== + +.. click:: SoftLayer.CLI.rwhois.edit:cli + :prog: rwhois edit + :show-nested: + +.. click:: SoftLayer.CLI.rwhois.show:cli + :prog: rwhois show + :show-nested: diff --git a/docs/cli/security_groups.rst b/docs/cli/security_groups.rst new file mode 100644 index 000000000..37385882d --- /dev/null +++ b/docs/cli/security_groups.rst @@ -0,0 +1,56 @@ +.. _cli_security_groups: + +Security Groups +=============== + +.. click:: SoftLayer.CLI.securitygroup.list:cli + :prog: securitygroup list + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.detail:cli + :prog: securitygroup detail + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.create:cli + :prog: securitygroup create + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.edit:cli + :prog: securitygroup edit + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.delete:cli + :prog: securitygroup delete + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.rule:rule_list + :prog: securitygroup rule-list + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.rule:add + :prog: securitygroup rule-add + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.rule:edit + :prog: securitygroup rule-edit + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.rule:remove + :prog: securitygroup rule-remove + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.interface:interface_list + :prog: securitygroup interface-list + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.interface:add + :prog: securitygroup interface-add + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.interface:remove + :prog: securitygroup interface-remove + :show-nested: + +.. click:: SoftLayer.CLI.securitygroup.event_log:get_by_request_id + :prog: securitygroup event-log + :show-nested: diff --git a/docs/cli/sshkey.rst b/docs/cli/sshkey.rst new file mode 100644 index 000000000..d12d2f424 --- /dev/null +++ b/docs/cli/sshkey.rst @@ -0,0 +1,24 @@ +.. _cli_sshkey: + +SSH Keys +======== + +.. click:: SoftLayer.CLI.sshkey.add:cli + :prog: sshkey add + :show-nested: + +.. click:: SoftLayer.CLI.sshkey.remove:cli + :prog: sshkey remove + :show-nested: + +.. click:: SoftLayer.CLI.sshkey.edit:cli + :prog: sshkey edit + :show-nested: + +.. click:: SoftLayer.CLI.sshkey.list:cli + :prog: sshkey list + :show-nested: + +.. click:: SoftLayer.CLI.sshkey.print:cli + :prog: sshkey print + :show-nested: diff --git a/docs/cli/ssl.rst b/docs/cli/ssl.rst new file mode 100644 index 000000000..f8c95f058 --- /dev/null +++ b/docs/cli/ssl.rst @@ -0,0 +1,25 @@ +.. _cli_ssl: + +SSL Certificates +================ + +.. click:: SoftLayer.CLI.ssl.add:cli + :prog: ssl add + :show-nested: + +.. click:: SoftLayer.CLI.ssl.download:cli + :prog: ssl download + :show-nested: + +.. click:: SoftLayer.CLI.ssl.edit:cli + :prog: ssl edit + :show-nested: + +.. click:: SoftLayer.CLI.ssl.list:cli + :prog: ssl list + :show-nested: + +.. click:: SoftLayer.CLI.ssl.remove:cli + :prog: ssl remove + :show-nested: + diff --git a/docs/cli/subnet.rst b/docs/cli/subnet.rst new file mode 100644 index 000000000..20fce0def --- /dev/null +++ b/docs/cli/subnet.rst @@ -0,0 +1,24 @@ +.. _cli_subnets: + +Subnets +======= + +.. click:: SoftLayer.CLI.subnet.cancel:cli + :prog: subnet cancel + :show-nested: + +.. click:: SoftLayer.CLI.subnet.create:cli + :prog: subnet create + :show-nested: + +.. click:: SoftLayer.CLI.subnet.detail:cli + :prog: subnet detail + :show-nested: + +.. click:: SoftLayer.CLI.subnet.list:cli + :prog: subnet list + :show-nested: + +.. click:: SoftLayer.CLI.subnet.lookup:cli + :prog: subnet lookup + :show-nested: diff --git a/docs/cli/tickets.rst b/docs/cli/tickets.rst new file mode 100644 index 000000000..ad5f23428 --- /dev/null +++ b/docs/cli/tickets.rst @@ -0,0 +1,40 @@ +.. _cli_tickets: + +Support Tickets +=============== + +.. click:: SoftLayer.CLI.ticket.create:cli + :prog: ticket create + :show-nested: + +.. click:: SoftLayer.CLI.ticket.detail:cli + :prog: ticket detail + :show-nested: + +.. click:: SoftLayer.CLI.ticket.list:cli + :prog: ticket list + :show-nested: + +.. click:: SoftLayer.CLI.ticket.update:cli + :prog: ticket update + :show-nested: + +.. click:: SoftLayer.CLI.ticket.upload:cli + :prog: ticket upload + :show-nested: + +.. click:: SoftLayer.CLI.ticket.subjects:cli + :prog: ticket subjects + :show-nested: + +.. click:: SoftLayer.CLI.ticket.summary:cli + :prog: ticket summary + :show-nested: + +.. click:: SoftLayer.CLI.ticket.attach:cli + :prog: ticket attach + :show-nested: + +.. click:: SoftLayer.CLI.ticket.detach:cli + :prog: ticket detach + :show-nested: diff --git a/docs/cli/users.rst b/docs/cli/users.rst index 3c98199a7..5058d0652 100644 --- a/docs/cli/users.rst +++ b/docs/cli/users.rst @@ -4,93 +4,32 @@ Users ============= Version 5.6.0 introduces the ability to interact with user accounts from the cli. -.. _cli_user_create: +.. click:: SoftLayer.CLI.user.list:cli + :prog: user list + :show-nested: -user create ------------ -This command will create a user on your account. +.. click:: SoftLayer.CLI.user.detail:cli + :prog: user detail + :show-nested: -Options -^^^^^^^ --e, --email TEXT Email address for this user. Required for creation. [required] --p, --password TEXT Password to set for this user. If no password is provided, user will be sent an email to generate one, which expires in 24 hours. '-p generate' will create a password for you (Requires Python 3.6+). Passwords require 8+ characters, upper and lowercase, a number and a symbol. --u, --from-user TEXT Base user to use as a template for creating this user. Will default to the user running this command. Information provided in --template supersedes this template. --t, --template TEXT A json string describing https://softlayer.github.io/reference/datatypes/SoftLayer_User_Customer/ --a, --api-key Create an API key for this user. --h, --help Show this message and exit. +.. click:: SoftLayer.CLI.user.permissions:cli + :prog: user permissions + :show-nested: -:: +.. click:: SoftLayer.CLI.user.edit_permissions:cli + :prog: user edit-permissions + :show-nested: - slcli user create my@email.com -e my@email.com -p generate -a -t '{"firstName": "Test", "lastName": "Testerson"}' +.. click:: SoftLayer.CLI.user.edit_details:cli + :prog: user edit-details + :show-nested: -.. _cli_user_list: +.. click:: SoftLayer.CLI.user.create:cli + :prog: user create + :show-nested: -user list ----------- -This command will list all Active users on the account that your user has access to view. -There is the option to also filter by username +.. click:: SoftLayer.CLI.user.delete:cli + :prog: user delete + :show-nested: -.. _cli_user_detail: - -user detail -------------------- -Gives a variety of details about a specific user. can be a user id, or username. Will always print a basic set of information about the user, but there are a few extra flags to pull in more detailed information. - -user detail -p, --permissions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Will list the permissions the user has. To see a list of all possible permissions, or to change a user's permissions, see :ref:`cli_user_permissions` - -user detail -h, --hardware -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Will list the Hardware and Dedicated Hosts the user is able to access. - - -user detail -v, --virtual -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Will list the Virtual Guests the user has access to. - -user detail -l, --logins -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Show login history of this user for the last 30 days. IBMId Users will show logins properly, but may not show failed logins. - -user detail -e, --events -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Shows things that are logged in the Event_Log service. Logins, reboots, reloads, and other such actions will show up here. - -.. _cli_user_permissions: - -user permissions -^^^^^^^^^^^^^^^^^^^^^^^ -Will list off all permission keyNames, along with which are assigned to that specific user. - -.. _cli_user_permissions_edit: - -user edit-permissions ---------------------- -Enable or Disable specific permissions. It is possible to set multiple permissions in one command as well. - -:: - - $ slcli user edit-permissions USERID --enable -p TICKET_EDIT -p TICKET_ADD -p TICKET_SEARCH - -Will enable TICKET_EDIT, TICKET_ADD, and TICKET_SEARCH permissions for the USERID - -.. _cli_user_edit_details: - -user edit-details ------------------ -Edit a User's details - -JSON strings should be enclosed in '' and each item should be enclosed in "\" - -:: - - slcli user edit-details testUser -t '{"firstName": "Test", "lastName": "Testerson"}' - -Options -^^^^^^^ - --t, --template TEXT A json string describing `SoftLayer_User_Customer `_ . [required] --h, --help Show this message and exit. - diff --git a/docs/cli/vlan.rst b/docs/cli/vlan.rst new file mode 100644 index 000000000..1733f40e4 --- /dev/null +++ b/docs/cli/vlan.rst @@ -0,0 +1,12 @@ +.. _cli_vlan: + +VLANs +===== + +.. click:: SoftLayer.CLI.vlan.detail:cli + :prog: vlan detail + :show-nested: + +.. click:: SoftLayer.CLI.vlan.list:cli + :prog: vlan list + :show-nested: diff --git a/docs/cli/vs.rst b/docs/cli/vs.rst index f855238d5..afa0f8b2d 100644 --- a/docs/cli/vs.rst +++ b/docs/cli/vs.rst @@ -10,18 +10,19 @@ using SoftLayer's command-line client. .. note:: - The following assumes that the client is already - :ref:`configured with valid SoftLayer credentials`. + The following assumes that the client is already + :ref:`configured with valid SoftLayer credentials`. First, let's list the current virtual servers with `slcli vs list`. + :: - $ slcli vs list - :.....:............:.........................:.......:........:..............:.............:....................:........: - : id : datacenter : host : cores : memory : primary_ip : backend_ip : active_transaction : owner : - :.....:............:.........................:.......:........:..............:.............:....................:........: - :.....:............:.........................:.......:........:..............:.............:....................:........: + $ slcli vs list + :.....:............:.........................:.......:........:..............:.............:....................:........: + : id : datacenter : host : cores : memory : primary_ip : backend_ip : active_transaction : owner : + :.....:............:.........................:.......:........:..............:.............:....................:........: + :.....:............:.........................:.......:........:..............:.............:....................:........: We don't have any virtual servers yet! Let's fix that. Before we can create a virtual server (VS), we need to know what options are available to us: RAM, @@ -32,47 +33,47 @@ Luckily, there's a simple command to show all options: `slcli vs create-options` :: - $ slcli vs create-options - :................................:.................................................................................: - : name : value : - :................................:.................................................................................: - : datacenter : ams01 : - : : ams03 : - : : wdc07 : - : flavors (balanced) : B1_1X2X25 : - : : B1_1X2X25 : - : : B1_1X2X100 : - : cpus (standard) : 1,2,4,8,12,16,32,56 : - : cpus (dedicated) : 1,2,4,8,16,32,56 : - : cpus (dedicated host) : 1,2,4,8,12,16,32,56 : - : memory : 1024,2048,4096,6144,8192,12288,16384,32768,49152,65536,131072,247808 : - : memory (dedicated host) : 1024,2048,4096,6144,8192,12288,16384,32768,49152,65536,131072,247808 : - : os (CENTOS) : CENTOS_5_64 : - : : CENTOS_LATEST_64 : - : os (CLOUDLINUX) : CLOUDLINUX_5_64 : - : : CLOUDLINUX_6_64 : - : : CLOUDLINUX_LATEST : - : : CLOUDLINUX_LATEST_64 : - : os (COREOS) : COREOS_CURRENT_64 : - : : COREOS_LATEST : - : : COREOS_LATEST_64 : - : os (DEBIAN) : DEBIAN_6_64 : - : : DEBIAN_LATEST_64 : - : os (OTHERUNIXLINUX) : OTHERUNIXLINUX_1_64 : - : : OTHERUNIXLINUX_LATEST : - : : OTHERUNIXLINUX_LATEST_64 : - : os (REDHAT) : REDHAT_5_64 : - : : REDHAT_6_64 : - : : REDHAT_7_64 : - : : REDHAT_LATEST : - : : REDHAT_LATEST_64 : - : san disk(0) : 25,100 : - : san disk(2) : 10,20,25,30,40,50,75,100,125,150,175,200,250,300,350,400,500,750,1000,1500,2000 : - : local disk(0) : 25,100 : - : local disk(2) : 25,100,150,200,300 : - : local (dedicated host) disk(0) : 25,100 : - : nic (dedicated host) : 100,1000 : - :................................:.................................................................................: + $ slcli vs create-options + :................................:.................................................................................: + : name : value : + :................................:.................................................................................: + : datacenter : ams01 : + : : ams03 : + : : wdc07 : + : flavors (balanced) : B1_1X2X25 : + : : B1_1X2X25 : + : : B1_1X2X100 : + : cpus (standard) : 1,2,4,8,12,16,32,56 : + : cpus (dedicated) : 1,2,4,8,16,32,56 : + : cpus (dedicated host) : 1,2,4,8,12,16,32,56 : + : memory : 1024,2048,4096,6144,8192,12288,16384,32768,49152,65536,131072,247808 : + : memory (dedicated host) : 1024,2048,4096,6144,8192,12288,16384,32768,49152,65536,131072,247808 : + : os (CENTOS) : CENTOS_5_64 : + : : CENTOS_LATEST_64 : + : os (CLOUDLINUX) : CLOUDLINUX_5_64 : + : : CLOUDLINUX_6_64 : + : : CLOUDLINUX_LATEST : + : : CLOUDLINUX_LATEST_64 : + : os (COREOS) : COREOS_CURRENT_64 : + : : COREOS_LATEST : + : : COREOS_LATEST_64 : + : os (DEBIAN) : DEBIAN_6_64 : + : : DEBIAN_LATEST_64 : + : os (OTHERUNIXLINUX) : OTHERUNIXLINUX_1_64 : + : : OTHERUNIXLINUX_LATEST : + : : OTHERUNIXLINUX_LATEST_64 : + : os (REDHAT) : REDHAT_5_64 : + : : REDHAT_6_64 : + : : REDHAT_7_64 : + : : REDHAT_LATEST : + : : REDHAT_LATEST_64 : + : san disk(0) : 25,100 : + : san disk(2) : 10,20,25,30,40,50,75,100,125,150,175,200,250,300,350,400,500,750,1000,1500,2000 : + : local disk(0) : 25,100 : + : local disk(2) : 25,100,150,200,300 : + : local (dedicated host) disk(0) : 25,100 : + : nic (dedicated host) : 100,1000 : + :................................:.................................................................................: Here's the command to create a 2-core virtual server with 1GiB memory, running @@ -81,8 +82,8 @@ datacenter using the command `slcli vs create`. :: - $ slcli vs create --hostname=example --domain=softlayer.com -f B1_1X2X25 -o DEBIAN_LATEST_64 --datacenter=ams01 --billing=hourly - This action will incur charges on your account. Continue? [y/N]: y + $ slcli vs create --hostname=example --domain=softlayer.com -f B1_1X2X25 -o DEBIAN_LATEST_64 --datacenter=ams01 --billing=hourly + This action will incur charges on your account. Continue? [y/N]: y :..........:.................................:......................................:...........................: : ID : FQDN : guid : Order Date : :..........:.................................:......................................:...........................: @@ -115,20 +116,20 @@ instantly appear in your virtual server list now. :: - $ slcli vs list - :.........:............:.......................:.......:........:................:..............:....................: - : id : datacenter : host : cores : memory : primary_ip : backend_ip : active_transaction : - :.........:............:.......................:.......:........:................:..............:....................: - : 1234567 : ams01 : example.softlayer.com : 2 : 1G : 108.168.200.11 : 10.54.80.200 : Assign Host : - :.........:............:.......................:.......:........:................:..............:....................: + $ slcli vs list + :.........:............:.......................:.......:........:................:..............:....................: + : id : datacenter : host : cores : memory : primary_ip : backend_ip : active_transaction : + :.........:............:.......................:.......:........:................:..............:....................: + : 1234567 : ams01 : example.softlayer.com : 2 : 1G : 108.168.200.11 : 10.54.80.200 : Assign Host : + :.........:............:.......................:.......:........:................:..............:....................: Cool. You may ask, "It's creating... but how do I know when it's done?" Well, here's how: :: - $ slcli vs ready 'example' --wait=600 - READY + $ slcli vs ready 'example' --wait=600 + READY When the previous command returns, you'll know that the virtual server has finished the provisioning process and is ready to use. This is *very* useful @@ -140,34 +141,34 @@ username is 'root' and password is 'ABCDEFGH'. .. warning:: - Be careful when using the `--passwords` flag. This will print the virtual - server's password on the screen. Make sure no one is looking over your - shoulder. It's also advisable to change your root password soon after - creating your virtual server, or to create a user with sudo access and - disable SSH-based login directly to the root account. + Be careful when using the `--passwords` flag. This will print the virtual + server's password on the screen. Make sure no one is looking over your + shoulder. It's also advisable to change your root password soon after + creating your virtual server, or to create a user with sudo access and + disable SSH-based login directly to the root account. :: - $ slcli vs detail example --passwords - :..............:...........................: - : Name : Value : - :..............:...........................: - : id : 1234567 : - : hostname : example.softlayer.com : - : status : Active : - : state : Running : - : datacenter : ams01 : - : cores : 2 : - : memory : 1G : - : public_ip : 108.168.200.11 : - : private_ip : 10.54.80.200 : - : os : Debian : - : private_only : False : - : private_cpu : False : - : created : 2013-06-13T08:29:44-06:00 : - : modified : 2013-06-13T08:31:57-06:00 : - : users : root ABCDEFGH : - :..............:...........................: + $ slcli vs detail example --passwords + :..............:...........................: + : Name : Value : + :..............:...........................: + : id : 1234567 : + : hostname : example.softlayer.com : + : status : Active : + : state : Running : + : datacenter : ams01 : + : cores : 2 : + : memory : 1G : + : public_ip : 108.168.200.11 : + : private_ip : 10.54.80.200 : + : os : Debian : + : private_only : False : + : private_cpu : False : + : created : 2013-06-13T08:29:44-06:00 : + : modified : 2013-06-13T08:31:57-06:00 : + : users : root ABCDEFGH : + :..............:...........................: diff --git a/docs/cli_directory.rst b/docs/cli_directory.rst new file mode 100644 index 000000000..6be40cc90 --- /dev/null +++ b/docs/cli_directory.rst @@ -0,0 +1,10 @@ +.. _cli_directory: + +Command Directory +================= + +.. toctree:: + :maxdepth: 2 + :glob: + + cli/* diff --git a/docs/dev/cli.rst b/docs/dev/cli.rst index 31853174e..9545253aa 100644 --- a/docs/dev/cli.rst +++ b/docs/dev/cli.rst @@ -48,6 +48,7 @@ Then we need to register it so that `slcli table-example` will know to route to ... Which gives us + :: $ slcli table-example @@ -143,32 +144,46 @@ All commands should be documented, luckily there is a sphinx module that makes t If you were adding a summary command to `slcli account` you would find the documentation in `docs/cli/account.rst` and you would just need to add this for your command -``` -.. click:: SoftLayer.CLI.account.summary:cli - :prog: account summary - :show-nested: -``` +:: + + .. click:: SoftLayer.CLI.account.summary:cli + :prog: account summary + :show-nested: The following REGEX can take the route entry and turn it into a document entry. -``` -s/^\('([a-z]*):([a-z-]*)', '([a-zA-Z\.:_]*)'\),$/.. click:: $3\n :prog: $1 $2\n :show-nested:\n/ -``` +:: + + s/^\('([a-z]*):([a-z-]*)', '([a-zA-Z\.:_]*)'\),$/.. click:: $3\n :prog: $1 $2\n :show-nested:\n/ + + +Find:: + + ^\('([a-z]*):([a-z-]*)', '([a-zA-Z\.:_]*)'\),$ -FIND: -``` -^\('([a-z]*):([a-z-]*)', '([a-zA-Z\.:_]*)'\),$ -``` -REPLACE: -``` -.. click:: $3 - :prog: $1 $2 - :show-nested: +REPLACE:: -``` + .. click:: $3 + :prog: $1 $2 + :show-nested: I tried to get sphinx-click to auto document the ENTIRE slcli, but the results were all on one page, and required a few changes to sphinx-click itself to work. This is due to the fact that most commands in SLCLI use the function name "cli", and some hacks would have to be put inplace to use the path name instead. + + +Architecture +------------ + +*SLCLI* is the base command, and it starts at *SoftLayer\CLI\core.py*. Commands are loaded from the *SoftLayer\CLI\routes.py* file. How Click figures this out is defined by the *CommandLoader* class in core.py, which is an example of a `MultiCommand `_. + +There are a few examples of commands that are three levels deep, that use a bit more graceful command loader. + +- *SoftLayer\CLI\virt\capacity\__init__.py* +- *SoftLayer\CLI\virt\placementgroup\__init__.py* +- *SoftLayer\CLI\object_storage\credential\__init__.py* + +These commands are not directly listed in the routes file, because the autoloader doesn't have the ability to parse multiple commands like that. For now it was easier to make the rare thrid level commands have their own special loader than re-write the base command loader to be able to look deeper into the project for commands. + diff --git a/docs/index.rst b/docs/index.rst index 1b3c2b390..1d801d53d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,6 +21,7 @@ in order to manage SoftLayer services. config_file api/* cli + cli_directory Contributing