Migrate readme yaml (#19)

* Migrate readme yaml

* Move link to reference section

* Regenerate README.md

* Minor fixes

.gitignore

@@ -7,3 +7,6 @@
 .terraform
 .idea
 *.iml
+
+.build-harness
+build-harness

Makefile

@@ -1,6 +1,10 @@
 SHELL := /bin/bash
 
+# List of targets the `readme` target should call before generating the readme
+export README_DEPS ?= docs/targets.md docs/terraform.md
+
 -include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
 
+## Lint terraform code
 lint:
-	$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate
+	$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate

README.yaml

@@ -0,0 +1,102 @@
+---
+#
+# This is the canonical configuration for the `README.md`
+# Run `make readme` to rebuild the `README.md`
+#
+
+# Name of this project
+name: terraform-aws-s3-website
+
+# Logo for this project
+#logo: docs/logo.png
+
+# License of this project
+license: "APACHE2"
+
+# Canonical GitHub repo
+github_repo: cloudposse/terraform-aws-s3-website
+
+# Badges to display
+badges:
+  - name: "Build Status"
+    image: "https://travis-ci.org/cloudposse/terraform-aws-s3-website.svg?branch=master"
+    url: "https://travis-ci.org/cloudposse/terraform-aws-s3-website"
+  - name: "Latest Release"
+    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-s3-website.svg"
+    url: "https://github.com/cloudposse/terraform-aws-s3-website/releases/latest"
+  - name: "Slack Community"
+    image: "https://slack.cloudposse.com/badge.svg"
+    url: "https://slack.cloudposse.com"
+
+related:
+  - name: "terraform-aws-cloudfront-s3-cdn"
+    description: "Terraform module to easily provision CloudFront CDN backed by an S3 origin"
+    url: "https://github.com/cloudposse/terraform-aws-cloudfront-s3-cdn"
+  - name: "terraform-aws-s3-log-storage"
+    description: "This module creates an S3 bucket suitable for receiving logs from other AWS services such as S3, CloudFront, and CloudTrail"
+    url: "https://github.com/cloudposse/terraform-aws-s3-log-storage"
+  - name: "terraform-aws-user-data-s3-backend"
+    description: "Terraform Module to Offload User Data to S3"
+    url: "https://github.com/cloudposse/terraform-aws-user-data-s3-backend"
+  - name: "terraform-aws-s3-logs-athena-query"
+    description: "A Terraform module that creates an Athena Database and Structure for querying S3 access logs"
+    url: "https://github.com/cloudposse/terraform-aws-s3-logs-athena-query"
+  - name: "terraform-aws-lb-s3-bucket"
+    description: "Terraform module to provision an S3 bucket with built in IAM policy to allow AWS Load Balancers to ship access logs"
+    url: "https://github.com/cloudposse/terraform-aws-lb-s3-bucket"
+
+# Short description of this project
+description: |-
+  Terraform module to provision S3-backed Websites
+
+# How to use this project
+usage: |-
+  #### Create s3 website bucket
+
+  ```hcl
+  module "website" {
+    source    = "git::https://github.com/cloudposse/terraform-aws-s3-website.git?ref=master"
+    namespace = "cp"
+    stage     = "prod"
+    name      = "app"
+    hostname  = "docs.prod.cloudposse.org"
+
+    deployment_arns = {
+      "arn:aws:s3:::principal1" = ["/prefix1", "/prefix2"]
+      "arn:aws:s3:::principal2" = [""]
+    }
+  }
+  ```
+
+
+  #### Create S3 website bucket with Route53 DNS
+
+  Required one of the `parent_zone_id` or `parent_zone_name`
+
+  ```hcl
+  module "website_with_cname" {
+    source         = "git::https://github.com/cloudposse/terraform-aws-s3-website.git?ref=master"
+    namespace      = "cp"
+    stage          = "prod"
+    name           = "app"
+    hostname       = "docs.prod.cloudposse.org"
+    parent_zone_id = "XXXXXXXXXXXX"
+  }
+  ```
+references:
+  - name: "Hosting Websites on Amazon S3"
+    description: "Example: setting up a Static Website Using a Custom Domain"
+    url: "http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html"
+
+include:
+  - "docs/targets.md"
+  - "docs/terraform.md"
+
+# Contributors to this project
+contributors:
+  - name: "Erik Osterman"
+    github: "osterman"
+  - name: "Andriy Knysh"
+    github: "aknysh"
+  - name: "Vladimir"
+    github: "SweetOps"

docs/targets.md

@@ -0,0 +1,9 @@
+## Makefile Targets
+```
+Available targets:
+
+  help                                This help screen
+  help/all                            Display help for all targets
+  lint                                Lint terraform code
+
+```

docs/terraform.md

@@ -0,0 +1,48 @@
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
+| cors_allowed_headers | List of allowed headers | list | `<list>` | no |
+| cors_allowed_methods | List of allowed methods (e.g. ` GET, PUT, POST, DELETE, HEAD`) | list | `<list>` | no |
+| cors_allowed_origins | List of allowed origins (e.g. ` example.com, test.com`) | list | `<list>` | no |
+| cors_expose_headers | List of expose header in the response | list | `<list>` | no |
+| cors_max_age_seconds | Time in seconds that browser can cache the response | string | `3600` | no |
+| delimiter | Delimiter to be used between `name`, `namespace`, `stage`, etc. | string | `-` | no |
+| deployment_actions | List of actions to permit deployment ARNs to perform | list | `<list>` | no |
+| deployment_arns | (Optional) Map of deployment ARNs to lists of S3 path prefixes to grant `deployment_actions` permissions | map | `<map>` | no |
+| error_document | An absolute path to the document to return in case of a 4XX error | string | `404.html` | no |
+| force_destroy | Delete all objects from the bucket so that the bucket can be destroyed without error (e.g. `true` or `false`) | string | `` | no |
+| hostname | Name of website bucket in `fqdn` format (e.g. `test.example.com`). IMPORTANT! Do not add trailing dot (`.`) | string | - | yes |
+| index_document | Amazon S3 returns this index document when requests are made to the root domain or any of the subfolders | string | `index.html` | no |
+| lifecycle_rule_enabled | Lifecycle rule status (e.g. `true` or `false`) | string | `` | no |
+| logs_expiration_days | Number of days after which to expunge the objects | string | `90` | no |
+| logs_glacier_transition_days | Number of days after which to move the data to the glacier storage tier | string | `60` | no |
+| logs_standard_transition_days | Number of days to persist in the standard storage tier before moving to the glacier tier | string | `30` | no |
+| name | The Name of the application or solution  (e.g. `bastion` or `portal`) | string | - | yes |
+| namespace | Namespace (e.g. `cp` or `cloudposse`) | string | - | yes |
+| noncurrent_version_expiration_days | Specifies when noncurrent object versions expire | string | `90` | no |
+| noncurrent_version_transition_days | Number of days to persist in the standard storage tier before moving to the glacier tier infrequent access tier | string | `30` | no |
+| parent_zone_id | ID of the hosted zone to contain the record | string | `` | no |
+| parent_zone_name | Name of the hosted zone to contain the record | string | `` | no |
+| prefix | Prefix identifying one or more objects to which the rule applies | string | `` | no |
+| region | AWS region this bucket should reside in | string | `` | no |
+| replication_source_principal_arns | (Optional) List of principal ARNs to grant replication access from different AWS accounts | list | `<list>` | no |
+| routing_rules | A json array containing routing rules describing redirect behavior and when redirects are applied | string | `` | no |
+| stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
+| tags | Additional tags (e.g. `map('BusinessUnit','XYZ')`) | map | `<map>` | no |
+| versioning_enabled | State of versioning (e.g. `true` or `false`) | string | `` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| hostname | Bucket hostname |
+| s3_bucket_arn | Name of of website bucket |
+| s3_bucket_domain_name | Name of of website bucket |
+| s3_bucket_hosted_zone_id | The Route 53 Hosted Zone ID for this bucket's region |
+| s3_bucket_name | DNS record of website bucket |
+| s3_bucket_website_domain | The domain of the website endpoint |
+| s3_bucket_website_endpoint | The website endpoint URL |
+

output.tf

@@ -1,27 +1,34 @@
 output "hostname" {
-  value = "${var.hostname}"
+  value       = "${var.hostname}"
+  description = "Bucket hostname"
 }
 
 output "s3_bucket_name" {
-  value = "${aws_s3_bucket.default.id}"
+  value       = "${aws_s3_bucket.default.id}"
+  description = "DNS record of website bucket"
 }
 
 output "s3_bucket_domain_name" {
-  value = "${aws_s3_bucket.default.bucket_domain_name}"
+  value       = "${aws_s3_bucket.default.bucket_domain_name}"
+  description = "Name of of website bucket"
 }
 
 output "s3_bucket_arn" {
-  value = "${aws_s3_bucket.default.arn}"
+  value       = "${aws_s3_bucket.default.arn}"
+  description = "Name of of website bucket"
 }
 
 output "s3_bucket_website_endpoint" {
-  value = "${aws_s3_bucket.default.website_endpoint}"
+  value       = "${aws_s3_bucket.default.website_endpoint}"
+  description = "The website endpoint URL"
 }
 
 output "s3_bucket_website_domain" {
-  value = "${aws_s3_bucket.default.website_domain}"
+  value       = "${aws_s3_bucket.default.website_domain}"
+  description = "The domain of the website endpoint"
 }
 
 output "s3_bucket_hosted_zone_id" {
-  value = "${aws_s3_bucket.default.hosted_zone_id}"
+  value       = "${aws_s3_bucket.default.hosted_zone_id}"
+  description = "The Route 53 Hosted Zone ID for this bucket's region"
 }

variables.tf

@@ -1,24 +1,36 @@
-variable "name" {}
+variable "name" {
+  description = "The Name of the application or solution  (e.g. `bastion` or `portal`)"
+}
 
-variable "namespace" {}
+variable "namespace" {
+  description = "Namespace (e.g. `cp` or `cloudposse`)"
+}
 
-variable "stage" {}
+variable "stage" {
+  description = "Stage (e.g. `prod`, `dev`, `staging`)"
+}
 
 variable "attributes" {
-  type    = "list"
-  default = []
+  type        = "list"
+  default     = []
+  description = "Additional attributes (e.g. `policy` or `role`)"
 }
 
 variable "tags" {
-  type    = "map"
-  default = {}
+  type        = "map"
+  default     = {}
+  description = "Additional tags (e.g. `map('BusinessUnit','XYZ')`)"
 }
 
 variable "delimiter" {
-  default = "-"
+  type        = "string"
+  default     = "-"
+  description = "Delimiter to be used between `name`, `namespace`, `stage`, etc."
 }
 
-variable "hostname" {}
+variable "hostname" {
+  description = "Name of website bucket in `fqdn` format (e.g. `test.example.com`). IMPORTANT! Do not add trailing dot (`.`)"
+}
 
 variable "parent_zone_id" {
   description = "ID of the hosted zone to contain the record"
@@ -31,39 +43,47 @@ variable "parent_zone_name" {
 }
 
 variable "index_document" {
-  default = "index.html"
+  default     = "index.html"
+  description = "Amazon S3 returns this index document when requests are made to the root domain or any of the subfolders"
 }
 
 variable "error_document" {
-  default = "404.html"
+  default     = "404.html"
+  description = "An absolute path to the document to return in case of a 4XX error"
 }
 
 variable "routing_rules" {
-  default = ""
+  default     = ""
+  description = "A json array containing routing rules describing redirect behavior and when redirects are applied"
 }
 
 variable "cors_allowed_headers" {
-  type    = "list"
-  default = ["*"]
+  type        = "list"
+  default     = ["*"]
+  description = "List of allowed headers"
 }
 
 variable "cors_allowed_methods" {
-  type    = "list"
-  default = ["GET"]
+  type        = "list"
+  default     = ["GET"]
+  description = "List of allowed methods (e.g. ` GET, PUT, POST, DELETE, HEAD`) "
 }
 
 variable "cors_allowed_origins" {
-  type    = "list"
-  default = ["*"]
+  type        = "list"
+  default     = ["*"]
+  description = "List of allowed origins (e.g. ` example.com, test.com`)"
 }
 
 variable "cors_expose_headers" {
-  type    = "list"
-  default = ["ETag"]
+  type        = "list"
+  default     = ["ETag"]
+  description = "List of expose header in the response"
 }
 
 variable "cors_max_age_seconds" {
-  default = "3600"
+  default     = "3600"
+  description = "Time in seconds that browser can cache the response"
 }
 
 variable "logs_standard_transition_days" {
@@ -82,31 +102,38 @@ variable "logs_expiration_days" {
 }
 
 variable "lifecycle_rule_enabled" {
-  default = ""
+  default     = ""
+  description = "Lifecycle rule status (e.g. `true` or `false`)"
 }
 
 variable "prefix" {
-  default = ""
+  default     = ""
+  description = "Prefix identifying one or more objects to which the rule applies"
 }
 
 variable "noncurrent_version_transition_days" {
-  default = "30"
+  default     = "30"
+  description = "Number of days to persist in the standard storage tier before moving to the glacier tier infrequent access tier"
 }
 
 variable "noncurrent_version_expiration_days" {
-  default = "90"
+  default     = "90"
+  description = "Specifies when noncurrent object versions expire"
 }
 
 variable "region" {
-  default = ""
+  default     = ""
+  description = "AWS region this bucket should reside in"
 }
 
 variable "versioning_enabled" {
-  default = ""
+  default     = ""
+  description = "State of versioning (e.g. `true` or `false`)"
 }
 
 variable "force_destroy" {
-  default = ""
+  default     = ""
+  description = "Delete all objects from the bucket so that the bucket can be destroyed without error (e.g. `true` or `false`)"
 }
 
 variable "replication_source_principal_arns" {