s3:deploy documentation

[studds]

Add documentation for how the s3:deploy gets the bucket name and distro:

Take the following deploy target:

{
  "deploy-s3": {
    "builder": "@nx-aws/s3:deploy",
    "options": {
      "destPrefix": "public",
      "bucket": {
        "targetName": "docs:deploy-cf",
        "outputName": "WebBucket"
      },
      "distribution": {
        "targetName": "docs:deploy-cf",
        "outputName": "DistributionId"
      }
    },
    "configurations": {
      "production": {
        "stackSuffix": "prod"
      }
    }
  }
}

To deploy to S3 we need an s3 bucket and then CloudFront distribution (so that we can trigger an invalidation of the deployed files.) We assume that there is a CloudFormation template which creates the S3 bucket and CF distribution, and outputs the web bucket name and distribution id as stack outputs. The configuration above then retrieves those outputs. It works like this:

1. Retrieve the nx configuration for "docs:deploy-cf" (from targetName)
2. Calculate the stack name - taking into account the current stack suffix
3. Retrieve the stack outputs

So, for example if running nx deploy-s3 docs:

1. Retrieve the nx configuration for "docs-deploy-cf"
2. Re-create the stack name, in this case docs-dev because we're running with the default (dev) stackSuffix.
3. Retrieve outputs from the CloudFormation stack docs-dev
4. Get the values for WebBucket and DistributionId

Alternatively, if running nx deploy-s3 docs --configuration production:

1. Retrieve the nx configuration for "docs-deploy-cf"
2. Re-create the stack name, in this case docs-prod because we've over-ridden the default stackSuffix to prod
3. Retrieve outputs from the CloudFormation stack docs-prod
4. Get the values for WebBucket and DistributionId