diff --git a/docs/api.rst b/docs/dev/api.rst similarity index 100% rename from docs/api.rst rename to docs/dev/api.rst diff --git a/docs/index.rst b/docs/index.rst index 1671d2b..5afff97 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,8 +17,6 @@ sailing. It is designed for human consumption, and aims to have good defaults. -It also happens to be a library. - Caveats ------- @@ -40,26 +38,19 @@ User Guide ---------- .. toctree:: - :maxdepth: 2 + :maxdepth: 3 user/install - user/library - user/cli + user/basic + user/reference -API Documentation ------------------ +Developer / Contributor Guide +----------------------------- .. toctree:: :maxdepth: 2 - api - -Contributor Guide ------------------ - -.. toctree:: - :maxdepth: 1 - + dev/api dev/testing diff --git a/docs/user/basic.rst b/docs/user/basic.rst new file mode 100644 index 0000000..e356e2e --- /dev/null +++ b/docs/user/basic.rst @@ -0,0 +1,77 @@ +CLI Usage +========= + +Configure +--------- + +Set up your credentials and preferences: + +:: + + $ pontoon configure + +You'll be prompted for your Digital Ocean API credentials (`available +here `__), and whether you want +to use existing SSH credentials or for them to be generated (using +OpenSSH). + +The rest are preferences, and can be set at any time by running +configure again, editing the ``~/.pontoon`` config file (YAML format), +or by specifying them with options on the command line. + +Configuration File +------------------ + +Here's an example of the options set in the configuration file: + +:: + + api_token: foo-bar-baz + auth_key_name: Macbook.local + image: ubuntu-15-10-x32 + region: lon1 + size: 512mb + ssh_private_key: ~/.ssh/id_rsa + ssh_public_key: ~/.ssh/id_rsa.pub + username: root + +Managing Droplets is probably what you'll spend most of your time doing with pontoon. + +You can get a full list of subcommands and options by running: + +:: + + $ pontoon droplet --help + +Basic Usage +----------- + +Creating and destroying Droplets is very straight forward: + +:: + + $ pontoon droplet create my-droplet + Creating Droplet my-droplet (512mb using ubuntu-15-10-x32 in lon1)... + ...............active + $ pontoon droplet destroy my-droplet + Destroying ud1 and scrubbing data... + +To SSH into your Droplet: + +:: + + $ pontoon droplet ssh my-droplet + Welcome to Ubuntu 15.10 (GNU/Linux 4.2.0-27-generic i686) + + * Documentation: https://help.ubuntu.com/ + Last login: Sun Mar 6 10:41:17 2016 from 192.168.1.200 + +To get a list of your Droplets: + +:: + + $ pontoon droplet list + my-droplet: (512mb, ubuntu-15-10-x32, lon1, 104.236.32.182, active) + + +See the :doc:`reference` for more. diff --git a/docs/user/cli.rst b/docs/user/cli.rst deleted file mode 100644 index c15336e..0000000 --- a/docs/user/cli.rst +++ /dev/null @@ -1,88 +0,0 @@ -CLI Usage -========= - -Configure ---------- - -Set up your credentials and preferences: - -:: - - $ pontoon configure - -You'll be prompted for your Digital Ocean API credentials (`available -here `__), and whether you want -to use existing SSH credentials or for them to be generated (using -OpenSSH). - -The rest are preferences, and can be set at any time by running -configure again, editing the ``~/.pontoon`` config file (YAML format), -or by specifying them with options on the command line. - -Create your first Droplet! --------------------------- - -Now you can create your first droplet: - -:: - - $ pontoon droplet create foobar - Creating Droplet foobar (512MB using Ubuntu 12.04 x64 in Amsterdam 1)... - .......active - -SSH into your Droplet ---------------------- - -If everything's configured correctly, you should be able to SSH into -your Droplet like so: - -:: - - $ pontoon droplet ssh foobar - Welcome to Ubuntu 12.04 LTS (GNU/Linux 3.2.0-23-virtual x86_64) - - * Documentation: https://help.ubuntu.com/ - Last login: Fri May 3 18:23:56 2013 - root@foobar:~# - -List your Droplets ------------------- - -:: - - $ pontoon droplet list - foobar: (512MB, Ubuntu 12.04 x64, Amsterdam 1, 192.0.2.128, active) - -or for more detail: - -:: - - $ pontoon droplet list --detail - foobar - id: 998 - name: foobar - size: 512MB - image: Ubuntu 12.04 x64 - region: Amsterdam 1 - status: active - locked: False - private_ip_address: None - created_at: 2013-11-09T13:22:40Z - backups_active: False - ip_address: 192.0.2.128 - -Configuration file ------------------- - -Here's an example of the options set in the configuration file: - -:: - - api_token: foo-bar-baz - auth_key_name: Macbook.local - image: ubuntu-15-10-x32 - region: lon1 - size: 512mb - ssh_private_key: ~/.ssh/id_rsa - ssh_public_key: ~/.ssh/id_rsa.pub - username: root diff --git a/docs/user/install.rst b/docs/user/install.rst index 02f0d1c..4dfcd78 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -7,5 +7,6 @@ Via pip: $ pip install pontoon +Pontoon works with Pythons 2.6 through 3.5, and should work on any Linux/BSD with Python support. -More options coming. +It's also possible to use pontoon on Windows, though portions of the configuarion command (which make use of Linux CLI tools like OpenSSH) do not work. diff --git a/docs/user/library.rst b/docs/user/library.rst deleted file mode 100644 index 0b83407..0000000 --- a/docs/user/library.rst +++ /dev/null @@ -1,16 +0,0 @@ -Library Usage -============= - -To use pontoon's bundled library, install from pip, and use like so: - -:: - - >>> import pontoon.lib - >>> manager = pontoon.lib.Manager(token="secretspecialuniquesnowflake") - >>> droplets = manager.get_all_droplets() - >>> for droplet in my_droplets: - >>> droplet.shutdown() - -The library is a fork of `python-digitalocean `__, by Lorenzo Setale. - -Further documentation for the library can be found there! diff --git a/docs/user/reference.rst b/docs/user/reference.rst new file mode 100644 index 0000000..f084fc2 --- /dev/null +++ b/docs/user/reference.rst @@ -0,0 +1,463 @@ +Command Reference +================= + +A complete list of commands and their options. + +Available on the command line by appending ``--help`` to the command. + +Configure +--------- + +The ``configure`` command interactively configures pontoon. + +You're prompted for details and a configuration file is written to ``~/.pontoon``. + +Alternatively, you can manually place a config file at this location with this syntax: + +:: + + api_token: foo-bar-baz + auth_key_name: Macbook.local + image: ubuntu-15-10-x32 + region: lon1 + size: 512mb + ssh_private_key: ~/.ssh/id_rsa + ssh_public_key: ~/.ssh/id_rsa.pub + username: root + + +.. program:: pontoon configure + +.. option:: pontoon configure + + Launch interactive configuration of pontoon. + +Droplets +-------- + + +.. program:: pontoon droplet list + +.. option:: pontoon droplet list [options] + +.. option:: --detail + + Show full Droplet info. + +:: + + $ pontoon droplet list --detail + example.com + id: 3164444 + size: 512mb + image: ubuntu-14-04-x64 + region: nyc3 + ip_address: 104.236.32.182 + status: active + kernel: + id: 2233 + name: Ubuntu 14.04 x64 vmlinuz-3.13.0-37-generic + version: 3.13.0-37-generic + ... + +| + +.. program:: pontoon droplet create + +.. option:: pontoon droplet create [options] + +.. option:: --size size + + Droplet RAM allocation. e.g., 512mb + +.. option:: --image image + + Droplet image. + +.. option:: --region region + + Droplet region. + +.. option:: --keys keys... + + List of registered keys to add to Droplet(s) + +.. option:: --user-data userdata + + String of user data to pass to Droplet. + Include a file like: ``--user-data="$(cat file.yml)"`` + +.. option:: --private-networking + + Assign private address to Droplet (where available) + +.. option:: --disable-virtio + + Disable VirtIO. (not recommended) + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet ssh + +.. option:: pontoon droplet ssh [command] [options] + +.. option:: --user user + + Override configured username for SSH login. + +.. option:: --key path + + Override configured private key for SSH login. + +| + +.. program:: pontoon droplet rename + +.. option:: pontoon droplet rename [options] + + Rename a Droplet. Takes the current name as the first parameter, + and the new name as the second. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet resize + +.. option:: pontoon droplet resize [options] + + Resize a Droplet. Takes Droplet name as first paramter, size as second. + +.. option:: --yes + + Don't prompt for confirmation. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet snapshot + +.. option:: pontoon droplet snapshot [options] + + Snapshot a Droplet. Takes Droplet name as first paramter, snapshot name as second. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet show + +.. option:: pontoon droplet show [options] + + Resize a Droplet. Takes Droplet name as first paramter, size as second. + +.. option:: --field field + + Extract and return a single field. Access nested items with dot syntax, e.g.: + ``networks.v4.0.gateway`` + +| + +.. program:: pontoon droplet status + +.. option:: pontoon droplet status + + Return Droplet status. + +| + +.. program:: pontoon droplet destroy + +.. option:: pontoon droplet destroy + + Destroy a Droplet. + +| + +.. program:: pontoon droplet start + +.. option:: pontoon droplet start + + Start a Droplet. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet shutdown + +.. option:: pontoon droplet shutdown + + Shut down a Droplet. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet reboot + +.. option:: pontoon droplet reboot + + Reboot a Droplet (sending signal to OS). + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet restore + +.. option:: pontoon droplet restore + + Restore a Droplet from a snapshot. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet rebuild + +.. option:: pontoon droplet rebuild + + Rebuild a Droplet from a given image. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet powercycle + +.. option:: pontoon droplet powercycle + + Powercycle (hard restart) a Droplet. + +.. option:: --yes + + Don't prompt for confirmation. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet poweroff + +.. option:: pontoon droplet poweroff + + Power off (without signalling the OS) a Droplet. + +.. option:: --yes + + Don't prompt for confirmation. + +.. option:: --no-wait + + Don't wait for action to complete, return immediately. + +| + +.. program:: pontoon droplet passwordreset + +.. option:: pontoon droplet passwordreset + + Reset the root password on a Droplet. + +.. option:: --yes + + Don't prompt for confirmation. + +| + +.. program:: pontoon droplet backups + +.. option:: pontoon droplet backups + + Manage backups on a Droplet. + +.. option:: --enable + + Enable backups. + +.. option:: --disable + + Depracated by Digital Ocean for their v2 API release, + later added back but still deprecated here for the moment. + + +Events +------ + +These is an interface to Digital Ocean events. + +Events are usually only an implementation detail, and an interface is provided here only for completeness. + +.. program:: pontoon event show + +.. option:: pontoon event show + + Retrieve details for a particular event id. + + +Images +------ + +Public base images made available by Digital Ocean. + +.. program:: pontoon image list + +.. option:: pontoon image list [options] + + Retrieve a list of public images. + +.. option:: --with-ids + + Include image IDs in tabular output. + +| + +.. program:: pontoon image oses + +.. option:: pontoon image oses + + Retrive a list of Operating Systems for which there are base images. + +| + +.. program:: pontoon image show + +.. option:: pontoon image show + + Show details for a particular image, including regions where it is available. + + +Regions +------- + +Regions available to launch Droplets. + +.. program:: pontoon region list + +.. option:: pontoon region list + + List regions in which Droplets can be launched. + + +Sizes +------- + +Droplet sizes available. + +.. program:: pontoon size list + +.. option:: pontoon size list + + List sizes of Droplets which can be launched. + + +Snapshots +--------- + +Commands for interacting with snapshots. + +.. program:: pontoon snapshot list + +.. option:: pontoon snapshot list [options] + + List available snapshots. + +.. option:: --with-ids + + Include image IDs in tabular output. + +| + +.. program:: pontoon snapshot show + +.. option:: pontoon snapshot show + + Show snapshot details. + +| + +.. program:: pontoon snapshot destroy + +.. option:: pontoon snapshot destroy + + Destroy a snapshot. + +| + +.. program:: pontoon snapshot transfer + +.. option:: pontoon snapshot transfer + + Move a snapshot from one region to another. + A list of regions can be retrieved with ``pontoon region list`` + + +SSH Keys +-------- + +Manage SSH keys in your account. + + +.. program:: pontoon sshkey list + +.. option:: pontoon sshkey list + + List of SSH keys in account. + +| + +.. program:: pontoon sshkey add + +.. option:: pontoon sshkey add + + Register a *public* SSH key from the specified path to your account. + +| + +.. program:: pontoon sshkey show + +.. option:: pontoon sshkey show + + Retrive a public key by name. + +| + +.. program:: pontoon sshkey replace + +.. option:: pontoon sshkey replace + + Replace an existing key name with a new *public* key. + + +.. program:: pontoon sshkey destroy + +.. option:: pontoon sshkey destroy + + Remove a given key from Digital Ocean. + Note: this doesn't remove the key from any existing Droplets, just removes + it from the keys available to boot Droplets with. +