add extended tutorial to main pkg docs (closes #32)

DESCRIPTION

@@ -18,7 +18,8 @@ Imports:
     base64enc
 Suggests:
     testthat,
-    aws.ec2metadata
+    aws.ec2metadata,
+    ssh
 URL: https://github.com/cloudyr/aws.ec2
 BugReports: https://github.com/cloudyr/aws.ec2/issues
 RoxygenNote: 6.0.1

NAMESPACE

@@ -33,6 +33,7 @@ export(delete_subnet)
 export(delete_tags)
 export(delete_volume)
 export(delete_vpc)
+export(deregister_image)
 export(describe_gateways)
 export(describe_images)
 export(describe_instances)

R/aws.ec2-package.R

@@ -3,7 +3,83 @@
 #' @docType package
 #' @title AWS EC2 Client Package
 #' @description A simple client package for the Amazon Web Services (AWS) Elastic Cloud Compute (EC2) REST API.
+#' @details The examples below provide a complete workflow for setting up EC2 via this package and launching an instance.
 #' @author Thomas J. Leeper <[email protected]>
+#' @examples
+#' \dontrun{
+#' # check credentials
+#' aws.signature::locate_credentials()
+#' 
+#' # check EC2 account settings
+#' account_attrs()
+#' 
+#' # create an SSH keypair in EC2 and save locally
+#' my_keypair <- create_keypair("r-ec2-example")
+#' pem_file <- tempfile(fileext = ".pem")
+#' cat(my_keypair$keyMaterial, file = pem_file)
+#' 
+#' # create a "security group" allowing access from current IP
+#' my_sg <- create_sgroup("r-ec2-sg", "Allow my IP")
+#' ## authorize access from this IP
+#' try(authorize_ingress(my_sg))
+#' try(authorize_egress(my_sg))
+#' 
+#' # find an EC2 AMI, like: http://www.louisaslett.com/RStudio_AMI/
+#' my_image <- "ami-3b0c205e"
+#' 
+#' # Launch the instance using appropriate settings
+#' my_inst <- run_instances(image = my_image,
+#'                          type = "t2.nano",
+#'                          sgroup = my_sg,
+#'                          keypair = my_keypair)
+#' Sys.sleep(5L) # wait for instance to boot
+#' 
+#' # allocate an IPv4 address
+#' ip <- allocate_ip("vpc")
+#' 
+#' # associate IP with instane
+#' associate_ip(my_inst, ip)
+#' 
+#' 
+#' # login to instance through browser
+#' utils::browseURL(ip)
+#' 
+#' # login to instance through R
+#' library("ssh")
+#' session <- ssh::ssh_connect(paste0("ubuntu@", instance_ip), keyfile = pem_file, passwd = "rstudio")
+#' 
+#' # write a quick little R script to execute
+#' cat("'hello world!'\nsprintf('2+2 is %d', 2+2)\n", file = "helloworld.R")
+#' # upload it to instance
+#' invisible(ssh::scp_upload(session, "helloworld.R"))
+#' 
+#' # execute script on instance
+#' x <- ssh::ssh_exec_wait(session, "Rscript helloworld.R")
+#' 
+#' ## disconnect from instance
+#' ssh:ssh_disconnect(session)
+#' 
+#' 
+#' # create an image from the instance to reuse later
+#' my_image <- create_image(my_inst, "My Rstudio Image")
+#' 
+#' 
+#' # when finished, completely cleanup all EC2 material
+#' ## stop and terminate the instance
+#' stop_instances(i[[1L]])
+#' terminate_instances(i[[1L]])
+#' 
+#' ## revoke access from this IP to security group
+#' try(revoke_ingress(my_sg))
+#' try(revoke_egress(my_sg))
+#' 
+#' ## delete keypair
+#' delete_keypair(my_keypair)
+#' 
+#' ## release IP address
+#' release_ip(ips[[1L]])
+#' 
+#' }
 #' @keywords package 
 #' @seealso [account_attrs()] [run_instances()]
 NULL

R/create_image.R

@@ -12,6 +12,7 @@
 #' @template dots
 #' @return A list.
 #' @references
+#' <http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami.html>
 #' <http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html>
 #' <http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateImage.html>
 #' @examples
@@ -75,15 +76,16 @@ function(
     return(r)
 }
 
-# \url{http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami.html}
-# \url{http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RegisterImage.html}
-#' @keywords images
+# <http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RegisterImage.html>
+# @keywords images
 register_image <- function() {
 
     # NEED TO DO THIS
 
 }
 
+#' @rdname create_ami
+#' @export
 deregister_image <- function(image, ...) {
     query <- list(Action = "DeregisterImage", 
                   ImageId = get_imageid(image))

R/create_vpc.R

@@ -7,6 +7,7 @@
 #' @template dots
 #' @return For `create_vpc`, a list of class \dQuote{ec2_vpc}. For `delete_vpc`, a logical indicating whether the operation succeeded.
 #' @references
+#' <https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html>
 #' <http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateVpc.html>
 #' <http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteVpc.html>
 #' @examples

R/ebs_snapshots.R

@@ -1,7 +1,6 @@
 #' @rdname ebs_snapshots
 #' @title Elastic Block Store Snapshots
 #' @description Manage Elastic Block Store (EBS) volumes for EC2
-#' @param volume An object of class \dQuote{ec2_ebs_volume} or a character string containing a volume ID.
 #' @template volume
 #' @template snapshot
 #' @param description \dots