Implement new readme generator (#61)

.travis.yml

@@ -17,6 +17,7 @@ install:
 - make docker/login
 - make go/deps-build
 - make go/deps-dev
+- make readme/deps
 
 script:
 - make bash/lint

Makefile

@@ -4,6 +4,9 @@ export SELF ?= make
 export PATH := $(BUILD_HARNESS_PATH)/vendor:$(PATH)
 export DOCKER_BUILD_FLAGS ?=
 
+# List of targets the `readme` target should call before generating the readme
+export README_DEPS ?= docs/targets.md
+
 # Import Makefiles into current context
 include $(BUILD_HARNESS_PATH)/Makefile.*
 include $(BUILD_HARNESS_PATH)/modules/*/bootstrap.Makefile*
@@ -13,3 +16,6 @@ ifndef TRANSLATE_COLON_NOTATION
 %:
 	@$(SELF) $(subst :,/,$@) TRANSLATE_COLON_NOTATION=false
 endif
+
+
+

README.yaml

@@ -0,0 +1,108 @@
+---
+# 
+# This is the canonical configuration for the `README.md`
+# Run `make readme` to rebuild the `README.md`
+#
+
+# Name of this project
+name: Build Harness 
+
+# Logo for this project
+#logo: docs/logo.png
+
+# License of this project
+license: "APACHE2"
+
+# Canonical GitHub repo 
+github_repo: cloudposse/build-harness
+
+# Badges to display
+badges:
+  - name: "Build Status"
+    image: "https://travis-ci.org/cloudposse/build-harness.svg?branch=master"
+    url: "https://travis-ci.org/cloudposse/build-harness"
+  - name: "Latest Release"
+    image: "https://img.shields.io/github/release/cloudposse/build-harness.svg"
+    url: "https://github.com/cloudposse/build-harness/releases"
+  - name: "Slack Community"
+    image: "https://slack.cloudposse.com/badge.svg"
+    url: "https://slack.cloudposse.com"
+
+related:
+  - name: "Packages"
+    description: "Cloud Posse installer and distribution of native apps"
+    url: "https://github.com/cloudposse/packages"
+  - name: "Dev Harness"
+    description: "Cloud Posse Local Development Harness"
+    url: "https://github.com/cloudposse/dev"
+
+# Short description of this project
+description: |-
+  This `build-harness` is a collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more.
+  It's designed to work with CI/CD systems such as Travis CI, CircleCI and Jenkins.
+
+# How to use this project
+usage: |-
+  At the top of your `Makefile` add, the following...
+
+  ```make
+  -include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
+  ```
+
+  This will download a `Makefile` called `.build-harness` and include it at run-time. We recommend adding the `.build-harness` file to your `.gitignore`.
+
+  This automatically exposes many new targets that you can leverage throughout your build & CI/CD process.
+
+  Run `make help` for a list of available targets.
+
+  **NOTE:** the `/` is interchangable with the `:` in target names
+
+# Example usage
+examples: |-
+  Here are some real world examples:
+  - [`github-authorized-keys`](https://github.com/cloudposse/github-authorized-keys/) - A Golang project that leverages `docker/%`, `go/%`, `travis/%` targets
+  - [`charts`](https://github.com/cloudposse/charts/) - A collection of Helm Charts that leverages `docker/%` and `helm/%` targets
+  - [`bastion`](https://github.com/cloudposse/bastion/) - A docker image that leverages `docker/%` and `bash/lint` targets
+  - [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label/) - A terraform module that leverages `terraform/%` targets
+
+# How to get started quickly
+quickstart: |-
+  Here's how to get started...
+
+  1. `git clone https://github.com/cloudposse/build-harness.git` to pull down the repository
+  2. `make init` to initialize the [`build-harness`](https://github.com/cloudposse/build-harness/)
+
+# Other files to include in this README from the project folder
+include:
+  - "docs/targets.md"
+
+# Contributors to this project
+contributors:
+  - name: "Erik Osterman"
+    homepage: "https://github.com/osterman"
+    avatar: "http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144"
+    github: "osterman"
+  - name: "Igor Rodionov"
+    homepage: "https://github.com/goruha/"
+    avatar: "http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144"
+    github: "goruha"
+  - name: "Andriy Knysh"
+    homepage: "https://github.com/aknysh/"
+    avatar: "https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144"
+    github: "aknysh"
+  - name: "Konstantin"
+    homepage: "https://github.com/comeanother/"
+    avatar: "https://avatars1.githubusercontent.com/u/11299538?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144"
+    github: "comeanother"
+  - name: "Sergey"
+    homepage: "https://github.com/s2504s/"
+    avatar: "https://avatars1.githubusercontent.com/u/1134449?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144"
+    github: "s2504s"
+  - name: "Valeriy"
+    homepage: "https://github.com/drama17/"
+    avatar: "https://avatars1.githubusercontent.com/u/10601658?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144"
+    github: "drama17"
+  - name: "Vladimir"
+    homepage: "https://github.com/SweetOps/"
+    avatar: "https://avatars1.githubusercontent.com/u/26582191?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144"
+    github: "SweetOps"

docs/targets.md

@@ -0,0 +1,78 @@
+## Makefile Targets
+```
+Available targets:
+
+  aws/install                         Install aws cli bundle
+  bash/lint                           Lint all bash scripts
+  chamber/install                     Install chamber
+  codefresh/trigger/webhook           Trigger a CodeFresh WebHook
+  docker/build                        Build docker image
+  docker/login                        Login into docker hub
+  docs/copyright-add                  Add copyright headers to source code
+  geodesic/deploy                     Run a Jenkins Job to Deploy $(APP) with $(CANONICAL_TAG)
+  git/aliases-update                  Update git aliases
+  git/export                          Export git vars
+  git/show                            Show vars
+  git/submodules-update               Update submodules
+  github/download-private-release     Download release from github
+  github/download-public-release      Download release from github
+  go/build                            Build binary
+  go/build-all                        Build binary for all platforms
+  go/clean                            Clean compiled binary
+  go/clean-all                        Clean compiled binary and dependency
+  go/deps                             Install dependencies
+  go/deps-build                       Install dependencies for build
+  go/deps-dev                         Install development dependencies
+  go/fmt                              Format code according to Golang convention
+  go/install                          Install cli
+  go/lint                             Lint code
+  go/test                             Run tests
+  go/vet                              Vet code
+  helm/chart/build                    Build chart $CHART_NAME from $CHART_TPL
+  helm/chart/build-all                Build chart $CHART_NAME from $CHART_TPL for all available $SEMVERSIONS
+  helm/chart/clean                    Clean chart packages
+  helm/chart/create                   Create chart $CHART from starter scaffold
+  helm/chart/publish                  Publish chart $CHART_NAME to $REPO_GATEWAY_ENDPOINT
+  helm/chart/starter/fetch            Fetch starter
+  helm/chart/starter/remove           Remove starter
+  helm/chart/starter/update           Update starter
+  helm/delete/namespace               Delete all releases in a namespace as well as the namespace
+  helm/install                        Install helm
+  helm/repo/add                       Add $REPO_NAME from $REPO_ENDPOINT
+  helm/repo/add-current               Add helm remote dev repos
+  helm/repo/add-remote                Add helm remote repos
+  helm/repo/build                     Build repo
+  helm/repo/clean                     Clean helm repo
+  helm/repo/fix-perms                 Fix repo filesystem permissions
+  helm/repo/info                      Show repo info
+  helm/repo/lint                      Lint charts
+  helm/repo/update                    Update repo info
+  helm/serve/index                    Build index for serve helm charts
+  helm/toolbox/upsert                 Install or upgrade helm tiller 
+  helmfile/install                    Install helmfile
+  help                                This help screen
+  jenkins/run-job-with-tag            Run a Jenkins Job with $(TAG)
+  make/lint                           Lint all makefiles
+  packages/delete                     Delete packages
+  packages/install                    Install packages 
+  packages/install/%                  Install package (e.g. helm, helmfile, kubectl)
+  packages/reinstall                  Reinstall packages
+  packages/uninstall/%                Uninstall package (e.g. helm, helmfile, kubectl)
+  readme                              Alias for readme/build
+  readme/build                        Create README.md by building it from README.yaml
+  readme/init                         Create basic minimalistic .README.md template file
+  readme/lint                         Verify the `README.md` is up to date
+  semver/export                       Export semver vars
+  semver/show                         Show
+  stages/export                       Export stages vars
+  template/build                      Create $OUT file by building it from $IN template file
+  template/deps                       Install dependencies
+  terraform/get-modules               Ensure all modules can be fetched
+  terraform/get-plugins               Ensure all plugins can be fetched
+  terraform/install                   Install terraform
+  terraform/lint                      Lint check Terraform
+  terraform/validate                  Basic terraform sanity check
+  travis/docker-login                 Login into docker hub
+  travis/docker-tag-and-push          Tag & Push according Travis environment variables
+
+```

modules/docs/Makefile

@@ -0,0 +1,14 @@
+.PHONY : docs/targets.md
+## Update `docs/targets.md` from `make help`
+docs/targets.md:
+	@( \
+		echo "## Makefile Targets"; \
+		echo '```'; \
+		$(SELF) --no-print-directory --quiet --silent help | sed $$'s,\x1b\\[[0-9;]*[a-zA-Z],,g'; \
+		echo '```'; \
+	) > $@
+
+.PHONY : docs/terraform.md
+## Update `docs/terraform.md` from `terraform-docs`
+docs/terraform.md: packages/install/terraform-docs
+	@terraform-docs md . > $@

modules/packages/Makefile

@@ -1,7 +1,15 @@
 export INSTALL_PATH ?= $(BUILD_HARNESS_PATH)/vendor
-export PACKAGES_VERSION ?= 0.1.7
+export PACKAGES_VERSION ?= 0.2.1
 export PACKAGES_PATH ?= $(BUILD_HARNESS_PATH)/vendor/packages
 
+## Delete packages
+packages/delete:
+	rm -rf $(PACKAGES_PATH)
+
+## Reinstall packages
+packages/reinstall: packages/delete packages/install
+	@exit 0
+
 ## Install packages 
 packages/install:
 	@if [ ! -d $(PACKAGES_PATH) ]; then \

modules/readme/Makefile

@@ -1,23 +1,36 @@
+export README_LINT ?= $(TMP)/README.md
 export README_FILE ?= README.md
-export README_TEMPLATE_FILE ?= .$(README_FILE)
+export README_YAML ?= README.yaml
+export README_TEMPLATE_FILE ?= $(BUILD_HARNESS_PATH)/templates/README.md
+export README_TEMPLATE_YAML ?= $(BUILD_HARNESS_PATH)/templates/README.yaml
 
 ## Alias for readme/build
 readme: readme/build
 	@exit 0
 
-## Update table of contents in README.md
-readme/toc-update:
-	@doctoc --notitle --github $(README_FILE)
+readme/deps: packages/install/gomplate
+	@exit 0
 
 ## Create basic minimalistic .README.md template file
 readme/init:
-	@if [ -s ./$(README_TEMPLATE_FILE) ]; then \
-	  echo "$(README_TEMPLATE_FILE) already exists!"; \
+	@if [ -f $(README_YAML) ]; then \
+	  echo "$(README_YAML) already exists!"; \
 	else \
-	  cp $(BUILD_HARNESS_PATH)/templates/$(README_TEMPLATE_FILE) ./$(README_TEMPLATE_FILE) ; \
-	  echo "$(README_TEMPLATE_FILE) created!"; \
+	  cp $(README_TEMPLATE_YAML) $(README_YAML) ; \
+	  echo "$(README_YAML) created!"; \
 	fi;
 
-## Create README.md by building it from .README.md file
-readme/build:
-	@$(SELF) -s template/build IN=$(README_TEMPLATE_FILE) OUT=$(README_FILE)
+## Verify the `README.md` is up to date
+readme/lint:
+	@$(SELF) readme/build README_FILE=$(README_LINT) >/dev/null
+	@diff -ruN $(README_LINT) $(README_FILE)
+	@rm -f $(README_LINT)
+
+## Create README.md by building it from README.yaml
+readme/build: $(README_DEPS)
+	@mkdir -p docs
+	@gomplate --file $(README_TEMPLATE_FILE) \
+		--out $(README_FILE) \
+		--datasource config=$(README_YAML) \
+		--datasource includes='file://$(shell pwd)/?type=text/plain'
+	@echo "Generated $(README_FILE) from $(README_TEMPLATE_FILE) using data from $(README_TEMPLATE_YAML)"

modules/template/Makefile

@@ -1,5 +1,5 @@
 export GOMPLATE ?= $(BUILD_HARNESS_PATH)/vendor/gomplate
-GOMPLATE_VERSION ?= v2.2.0
+GOMPLATE_VERSION ?= v2.6.0
 GOMPLATE_REPO ?= hairyhenderson/gomplate
 
 ## Install dependencies