Merge pull request #3400 from petems/update_digital_ocean_docs

Update DigitalOcean docs

lib/fog/digitalocean/examples/getting_started.md

@@ -2,10 +2,7 @@
 
 You'll need a DigitalOcean account and API key to use this provider.
 
-Get one from http://www.digitalocean.com.
-
-To generate the API key, login to the DigitalOcean web panel and go to
-'My Settings -> API Access -> Generate a new API key'.
+Get one from https://cloud.digitalocean.com/api_access (fog currently uses the v1 API)
 
 Write down the Client Key and API Key, you'll need both to use the service.
 
@@ -29,6 +26,51 @@ docean = Fog::Compute.new({
 })
 ```
 
+## SSH Key Management
+
+Access to DigitalOcean servers can be managed with SSH keys. These can be assigned to servers at creation time so you can access them without having to use a password.
+
+Creating a key:
+
+```ruby
+docean.ssh_keys.create(
+  :name        => 'Default SSH Key',
+  :ssh_pub_key => File.read('~/.ssh/id_rsa.pub'))
+)
+```
+
+Listing all keys:
+
+```ruby
+docean.ssh_keys.each do | key |
+   key.name
+   key.ssh_pub_key
+end
+```
+
+Destroying a key:
+
+```ruby
+docean.ssh_keys.destroy(:id => '27100')
+```
+
+## Boostrapping a server
+
+Fog can be used to bootstrap a server, which will create an SSH key to be assigned to a server at boot.
+
+```ruby
+server = connection.servers.bootstrap({
+  :name => 'test',
+  :image_id => 1505447,
+  :size_id => 33,
+  :region_id => 4,
+  :flavor_id => 66,
+  :public_key_path => File.expand_path('~/.ssh/id_rsa.pub'),
+  :private_key_path => File.expand_path('~/.ssh/id_rsa'),
+})
+server.wait_for { ready? }
+```
+
 ## Listing servers
 
 Listing servers and attributes:

lib/fog/digitalocean/models/compute/server.rb

@@ -12,8 +12,6 @@ module Fog
         attribute :image_id
         attribute :region_id
         attribute :flavor_id, :aliases => 'size_id'
-        # Not documented in their API, but
-        # available nevertheless
         attribute :public_ip_address, :aliases => 'ip_address'
         attribute :private_ip_address
         attribute :private_networking
@@ -94,7 +92,7 @@ module Fog
             commands << %{echo "#{public_key}" >> ~/.ssh/authorized_keys}
           end
 
-          # wait for aws to be ready
+          # wait for DigitalOcean to be ready
           wait_for { sshable?(credentials) }
 
           Fog::SSH.new(ssh_ip_address, username, credentials).run(commands)

lib/fog/digitalocean/models/compute/servers.rb

@@ -7,11 +7,33 @@ module Fog
       class Servers < Fog::Collection
         model Fog::Compute::DigitalOcean::Server
 
+        # Returns list of servers
+        # @return [Fog::Compute::DigitalOcean::Servers] Retrieves a list of servers.
+        # @raise [Fog::Compute::DigitalOcean::NotFound] - HTTP 404
+        # @raise [Fog::Compute::DigitalOcean::BadRequest] - HTTP 400
+        # @raise [Fog::Compute::DigitalOcean::InternalServerError] - HTTP 500
+        # @raise [Fog::Compute::DigitalOcean::ServiceError]
+        # @see https://developers.digitalocean.com/v1/droplets/
         def all(filters = {})
           data = service.list_servers.body['droplets']
           load(data)
         end
 
+        # Creates a new server and populates ssh keys
+        #
+        # @return [Fog::Compute::DigitalOcean::Server]
+        # @raise [Fog::Compute::DigitalOcean::NotFound] - HTTP 404
+        # @raise [Fog::Compute::DigitalOcean::BadRequest] - HTTP 400
+        # @raise [Fog::Compute::DigitalOcean::InternalServerError] - HTTP 500
+        # @raise [Fog::Compute::DigitalOcean::ServiceError]
+        # @note This creates an SSH public key object and assigns it to the server on creation
+        # @example
+        #   service.servers.bootstrap :name => 'bootstrap-server',
+        #                             :flavor_ref => service.flavors.first.id,
+        #                             :image_ref => service.images.find {|img| img.name =~ /Ubuntu/}.id,
+        #                             :public_key_path => '~/.ssh/fog_rsa.pub',
+        #                             :private_key_path => '~/.ssh/fog_rsa'
+        #
         def bootstrap(new_attributes = {})
           server = new(new_attributes)
 
@@ -40,6 +62,14 @@ module Fog
           server
         end
 
+        # Retrieves server
+        # @param [String] id for server to be returned
+        # @return [Fog::Compute::DigitalOcean:Server]
+        # @raise [Fog::Compute::DigitalOcean::NotFound] - HTTP 404
+        # @raise [Fog::Compute::DigitalOcean::BadRequest] - HTTP 400
+        # @raise [Fog::Compute::DigitalOcean::InternalServerError] - HTTP 500
+        # @raise [Fog::Compute::DigitalOcean::ServiceError]
+        # @see https://developers.digitalocean.com/v1/droplets/
         def get(id)
           server = service.get_server_details(id).body['droplet']
           new(server) if server