Use README.yaml (#18)

* use README.yaml

* update gitignore

* use hcl for code blocks

* generate README

* regen README

* add missing descriptions

.gitignore

@@ -1,9 +1,13 @@
 # Compiled files
 *.tfstate
 *.tfstate.backup
+.terraform.tfstate.lock.info
 
 # Module directory
 .terraform/
-
 .idea
 *.iml
+
+# Build Harness
+.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

README.yaml

@@ -0,0 +1,112 @@
+---
+#
+# This is the canonical configuration for the `README.md`
+# Run `make readme` to rebuild the `README.md`
+#
+
+# Name of this project
+name: terraform-aws-codebuild
+
+# Logo for this project
+#logo: docs/logo.png
+
+# License of this project
+license: "APACHE2"
+
+# Canonical GitHub repo
+github_repo: cloudposse/terraform-aws-codebuild
+
+# Badges to display
+badges:
+  - name: "Build Status"
+    image: "https://travis-ci.org/cloudposse/terraform-aws-codebuild.svg?branch=master"
+    url: "https://travis-ci.org/cloudposse/terraform-aws-codebuild"
+  - name: "Latest Release"
+    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-codebuild.svg"
+    url: "https://github.com/cloudposse/terraform-aws-codebuild/releases"
+  - name: "Slack Community"
+    image: "https://slack.cloudposse.com/badge.svg"
+    url: "https://slack.cloudposse.com"
+
+related:
+  - name: "terraform-aws-ecs-codepipeline"
+    description: "Terraform Module for CI/CD with AWS Code Pipeline and Code Build for ECS"
+    url: "https://github.com/cloudposse/terraform-aws-ecs-codepipeline"
+
+# Short description of this project
+description: |-
+  Terraform module to create AWS CodeBuild project for AWS CodePipeline.
+
+# How to use this project
+usage: |-
+  Include this module in your existing terraform code:
+
+  ```hcl
+  module "build" {
+      source              = "git::https://github.com/cloudposse/terraform-aws-codebuild.git?ref=master"
+      namespace           = "general"
+      name                = "ci"
+      stage               = "staging"
+
+      # https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html
+      build_image         = "aws/codebuild/docker:1.12.1"
+      build_compute_type  = "BUILD_GENERAL1_SMALL"
+
+      # These attributes are optional, used as ENV variables when building Docker images and pushing them to ECR
+      # For more info:
+      # http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html
+      # https://www.terraform.io/docs/providers/aws/r/codebuild_project.html
+
+      privileged_mode     = "true"
+      aws_region          = "us-east-1"
+      aws_account_id      = "xxxxxxxxxx"
+      image_repo_name     = "ecr-repo-name"
+      image_tag           = "latest"
+
+      # Optional extra environment variables
+      environment_variables = [{
+          name  = "JENKINS_URL"
+          value = "https://jenkins.example.com"
+        },
+        {
+          name  = "COMPANY_NAME"
+          value = "Amazon"
+        },
+        {
+          name = "TIME_ZONE"
+          value = "Pacific/Auckland"
+
+        }]
+  }
+  ```
+
+  ### To hide warnings about unset versions in providers
+
+  Add this to your .tf files
+  ```hcl
+  provider "random" {
+    version = "~> 1.0"
+  }
+
+  provider "null" {
+    version = "~> 1.0"
+  }
+  ```
+
+# Other files to include in this README from the project folder
+include:
+  - "docs/targets.md"
+  - "docs/terraform.md"
+
+# Contributors to this project
+contributors:
+  - name: "Erik Osterman"
+    github: "osterman"
+  - name: "Igor Rodionov"
+    github: "goruha"
+  - name: "Andriy Knysh"
+    github: "aknysh"
+  - name: "Jamie Nelson"
+    github: "Jamie-BitfFlight"
+  - name: "Sarkis Varozian"
+    github: "sarkis"

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,35 @@
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
+| aws_account_id | (Optional) AWS Account ID. Used as CodeBuild ENV variable when building Docker images. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html | string | `` | no |
+| aws_region | (Optional) AWS Region, e.g. us-east-1. Used as CodeBuild ENV variable when building Docker images. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html | string | `` | no |
+| build_compute_type | Instance type of the build instance | string | `BUILD_GENERAL1_SMALL` | no |
+| build_image | Docker image for build environment, e.g. 'aws/codebuild/docker:1.12.1' or 'aws/codebuild/eb-nodejs-6.10.0-amazonlinux-64:4.0.0'. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref.html | string | `aws/codebuild/docker:1.12.1` | no |
+| buildspec | Optional buildspec declaration to use for building the project | string | `` | no |
+| cache_bucket_suffix_enabled | The cache bucket generates a random 13 character string to generate a unique bucket name. If set to false it uses terraform-null-label's id value | string | `true` | no |
+| cache_enabled | If cache_enabled is true, create an S3 bucket for storing codebuild cache inside | string | `true` | no |
+| cache_expiration_days | How many days should the build cache be kept | string | `7` | no |
+| delimiter | Delimiter to be used between `name`, `namespace`, `stage`, etc. | string | `-` | no |
+| enabled | A boolean to enable/disable resource creation | string | `true` | no |
+| environment_variables | A list of maps, that contain both the key 'name' and the key 'value' to be used as additional environment variables for the build. | list | `<list>` | no |
+| github_token | (Optional) GitHub auth token environment variable (`GITHUB_TOKEN`) | string | `` | no |
+| image_repo_name | (Optional) ECR repository name to store the Docker image built by this module. Used as CodeBuild ENV variable when building Docker images. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html | string | `UNSET` | no |
+| image_tag | (Optional) Docker image tag in the ECR repository, e.g. 'latest'. Used as CodeBuild ENV variable when building Docker images. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html | string | `latest` | no |
+| name | Solution name, e.g. 'app' or 'jenkins' | string | `codebuild` | no |
+| namespace | Namespace, which could be your organization name, e.g. 'cp' or 'cloudposse' | string | `global` | no |
+| privileged_mode | (Optional) If set to true, enables running the Docker daemon inside a Docker container on the CodeBuild instance. Used when building Docker images | string | `false` | no |
+| stage | Stage, e.g. 'prod', 'staging', 'dev', or 'test' | string | `default` | no |
+| tags | Additional tags (e.g. `map('BusinessUnit', 'XYZ')` | map | `<map>` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| cache_bucket_name | Cache S3 bucket name |
+| project_id | Project ID |
+| project_name | Project name |
+| role_arn | IAM Role ARN |
+

outputs.tf

@@ -1,15 +1,19 @@
 output "project_name" {
-  value = "${join("", aws_codebuild_project.default.*.name)}"
+  description = "Project name"
+  value       = "${join("", aws_codebuild_project.default.*.name)}"
 }
 
 output "project_id" {
-  value = "${join("", aws_codebuild_project.default.*.id)}"
+  description = "Project ID"
+  value       = "${join("", aws_codebuild_project.default.*.id)}"
 }
 
 output "role_arn" {
-  value = "${join("", aws_iam_role.default.*.id)}"
+  description = "IAM Role ARN"
+  value       = "${join("", aws_iam_role.default.*.id)}"
 }
 
 output "cache_bucket_name" {
-  value = "${var.enabled == "true" && var.cache_enabled == "true" ? join("", aws_s3_bucket.cache_bucket.*.bucket) : "UNSET" }"
+  description = "Cache S3 bucket name"
+  value       = "${var.enabled == "true" && var.cache_enabled == "true" ? join("", aws_s3_bucket.cache_bucket.*.bucket) : "UNSET" }"
 }

variables.tf

@@ -1,16 +1,19 @@
 variable "namespace" {
-  type    = "string"
-  default = "global"
+  type        = "string"
+  default     = "global"
+  description = "Namespace, which could be your organization name, e.g. 'cp' or 'cloudposse'"
 }
 
 variable "stage" {
-  type    = "string"
-  default = "default"
+  type        = "string"
+  default     = "default"
+  description = "Stage, e.g. 'prod', 'staging', 'dev', or 'test'"
 }
 
 variable "name" {
-  type    = "string"
-  default = "codebuild"
+  type        = "string"
+  default     = "codebuild"
+  description = "Solution name, e.g. 'app' or 'jenkins'"
 }
 
 variable "environment_variables" {
@@ -27,7 +30,7 @@ variable "environment_variables" {
 variable "enabled" {
   type        = "string"
   default     = "true"
-  description = "A boolean to enable/disable resource creation."
+  description = "A boolean to enable/disable resource creation"
 }
 
 variable "cache_enabled" {
@@ -39,7 +42,7 @@ variable "cache_enabled" {
 variable "cache_expiration_days" {
   type        = "string"
   default     = "7"
-  description = "How many days should the build cache be kept."
+  description = "How many days should the build cache be kept"
 }
 
 variable "cache_bucket_suffix_enabled" {
@@ -55,8 +58,9 @@ variable "build_image" {
 }
 
 variable "build_compute_type" {
-  type    = "string"
-  default = "BUILD_GENERAL1_SMALL"
+  type        = "string"
+  default     = "BUILD_GENERAL1_SMALL"
+  description = "Instance type of the build instance"
 }
 
 variable "buildspec" {
@@ -66,18 +70,21 @@ variable "buildspec" {
 }
 
 variable "delimiter" {
-  type    = "string"
-  default = "-"
+  type        = "string"
+  default     = "-"
+  description = "Delimiter to be used between `name`, `namespace`, `stage`, etc."
 }
 
 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 "privileged_mode" {