apply-setters and search-replace README and generated docs

functions/go/Makefile

@@ -15,6 +15,7 @@ SHELL=/bin/bash
 GOPATH := $(shell go env GOPATH)
 TAG ?= unstable
 GCR = gcr.io/kpt-fn
+GOBIN := $(shell go env GOPATH)/bin
 
 # Edit this list to contain all go functions
 FUNCTIONS := \
@@ -27,6 +28,8 @@ FUNCTIONS := \
 
 # Targets for running all function tests
 FUNCTION_TESTS := $(patsubst %,%-TEST,$(FUNCTIONS))
+# Targets for generating all functions docs
+FUNCTION_GENERATE_DOCS := $(patsubst %,%-GENERATE,$(FUNCTIONS))
 
 FUNCTION_CHECKLICENSES := $(patsubst %,%-CHECKLICENSES,$(FUNCTIONS))
 # Targets to build functions
@@ -55,6 +58,15 @@ test: $(FUNCTION_TESTS) ## Run unit tests for all functions
 $(FUNCTION_TESTS):
 	$(MAKE) CURRENT_FUNCTION=$(subst -TEST,,$@) func-test
 
+generate: install-mdtogo generate-docs
+
+.PHONY: generate-docs
+generate-docs: $(FUNCTION_GENERATE_DOCS) ## Generate docs for all functions
+
+.PHONY: $(FUNCTION_GENERATE_DOCS)
+$(FUNCTION_GENERATE_DOCS):
+	$(MAKE) CURRENT_FUNCTION=$(subst -GENERATE,,$@) docs-generate
+
 .PHONY: build
 build: $(FUNCTION_BUILDS) ## Build all function images. 'TAG' env is used to specify tag. 'dev' will be used if not set.
 
@@ -84,9 +96,12 @@ else
 GO_LICENSES=$(shell which go-licenses)
 endif
 
+install-mdtogo:
+	GO111MODULE=on go get -v github.com/GoogleContainerTools/kpt/mdtogo
+
 # Recipes for individual function
 .PHONY: func-fix func-vet func-fmt func-test func-lint \
-	func-build func-push func-verify func-check-licenses
+	func-build func-push func-verify func-check-licenses docs-generate
 func-verify: func-fix func-vet func-fmt func-test func-lint func-check-licenses
 
 func-fix:
@@ -117,3 +132,7 @@ func-build: func-verify
 func-push:
 	@echo Pushing image $(CURRENT_FUNCTION)...
 	../../scripts/go-function-release.sh push curated
+
+docs-generate:
+	$(GOBIN)/mdtogo $(CURRENT_FUNCTION) $(CURRENT_FUNCTION)/generated --license=none --strategy=cmdDocs
+

functions/go/apply-setters/README.md

@@ -0,0 +1,167 @@
+# apply-setters
+
+### Overview
+
+<!--mdtogo:Short-->
+
+Apply setter values on resource fields. Setters serve as parameters for template-free
+setting of field values.
+
+<!--mdtogo-->
+
+Setters are a safer alternative to other substitution techniques which do not have the context
+of the structured data. Setters may be invoked to modify the package resources
+using `apply-setters` function to set values.
+
+### Synopsis
+
+<!--mdtogo:Long-->
+
+Package publishers declare setters in the package, consumers can set their values
+either declaratively or imperatively.
+
+Setter names can be discovered in the pipeline section of Kptfile, and the values
+can be declared next to setter names.
+
+```yaml
+apiVersion: v1alpha2
+kind: Kptfile
+metadata:
+  name: my-pkg
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/apply-setters:unstable
+      configMap:
+        setter_name1: setter-value1
+        setter_name2: setter-value2
+```
+
+The declared values for setters are rendered by invoking the following command:
+
+```
+kpt fn render [PKG_PATH]
+```
+
+Alternatively, this function can be invoked imperatively on the package by passing the
+inputs as key-value pairs.
+
+```
+kpt fn eval --image gcr.io/kpt-fn/apply-setters:VERSION [PKG_PATH] -- [setter_name=setter_value]
+```
+
+<!--mdtogo-->
+
+### Examples
+
+<!--mdtogo:Examples-->
+
+#### Setting scalar values
+
+Let's start with the input resource in a package
+
+```yaml
+apiVersion: v1
+kind: Deployment
+metadata:
+  name: nginx-deployment # kpt-set: ${image}-deployment
+spec:
+  replicas: 1 # kpt-set: ${replicas}
+```
+
+Discover the names of setters in the Kptfile and declare desired values.
+
+```yaml
+apiVersion: v1alpha2
+kind: Kptfile
+metadata:
+  name: my-pkg
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/apply-setters:unstable
+      configMap:
+        image: ubuntu
+        replicas: 3
+```
+
+Render the declared values by invoking:
+
+```
+kpt fn render
+```
+
+Alternatively, values can be rendered imperatively
+
+```
+kpt fn eval --image gcr.io/kpt-fn/apply-setters:unstable -- 'replicas=3'
+```
+
+Rendered resource looks like the following:
+
+```yaml
+apiVersion: v1
+kind: Deployment
+metadata:
+  name: ubuntu-deployment # kpt-set: ${image}-deployment
+spec:
+  replicas: 3 # kpt-set: ${replicas}
+```
+
+#### Setting array values
+
+Array values can also be parameterized using setters. Since the values of configMap
+in pipeline definition must be of string type, the array values must be wrapped into
+string. However, the rendered values in the resources will be array type.
+
+Let's start with the input resource
+
+```yaml
+apiVersion: v1
+kind: MyKind
+metadata:
+  name: foo
+environments: # kpt-set: ${env}
+  - dev
+  - stage
+```
+
+Declare the desired array values, wrapped into string.
+
+```yaml
+apiVersion: v1alpha2
+kind: Kptfile
+metadata:
+  name: my-pkg
+pipeline:
+  mutators:
+    - image: gcr.io/kpt-fn/apply-setters:unstable
+      configMap:
+        env: |
+          - prod
+          - dev
+```
+
+Render the declared values by invoking:
+
+```
+kpt fn render
+```
+
+Alternatively, values can be rendered imperatively
+
+```
+kpt fn eval --image gcr.io/kpt-fn/apply-setters:unstable -- 'env=[prod, dev]'
+```
+
+Rendered resource looks like the following:
+
+```yaml
+apiVersion: v1
+kind: MyKind
+metadata:
+  name: foo
+environments: # kpt-set: ${env}
+  - prod
+  - dev
+```
+
+<!--mdtogo-->