kyaml: refactor command documentation into .md files from go files

No new documentation added.

cmd/config/docs/api-conventions/merge2.md

@@ -0,0 +1,91 @@
+# Merge (2-way)
+
+  2-way merges fields from a source to a destination, overriding the destination fields
+  where they differ.
+
+  ### Merge Rules
+
+  Fields are recursively merged using the following rules:
+
+  - scalars
+    - if present only in the dest, it keeps its value
+    - if present in the src and is non-null, take the src value -- if `null`, clear it
+    - example src: `5`, dest: `3` => result: `5`
+
+  - non-associative lists -- lists without a merge key
+    - if present only in the dest, it keeps its value
+    - if present in the src and is non-null, take the src value -- if `null`, clear it
+    - example src: `[1, 2, 3]`, dest: `[a, b, c]` => result: `[1, 2, 3]`
+
+  - map keys and fields -- paired by the map-key / field-name
+    - if present only in the dest, it keeps its value
+    - if present only in the src, it is added to the dest
+    - if the field is present in both the src and dest, and the src value is
+      `null`, the field is removed from the dest
+    - if the field is present in both the src and dest, the value is recursively merged
+    - example src: `{'key1': 'value1', 'key2': 'value2'}`, 
+      dest: `{'key2': 'value0', 'key3': 'value3'}`
+      => result: `{'key1': 'value1', 'key2': 'value2', 'key3': 'value3'}`
+
+  - associative list elements -- paired by the associative key
+    - if present only in the dest, it keeps its value in the list
+    - if present only in the src, it is added to the dest list
+    - if the field is present in both the src and dest, the value is recursively merged
+
+  ### Associative Keys
+
+  Associative keys are used to identify "same" elements within 2 different lists, and merge them.
+  The following fields are recognized as associative keys:
+
+  [`mountPath`, `devicePath`, `ip`, `type`, `topologyKey`, `name`, `containerPort`]
+
+  Any lists where all of the elements contain associative keys will be merged as associative lists.
+
+  ### Example
+
+  > Source
+
+	apiVersion: apps/v1
+	kind: Deployment
+	spec:
+	  replicas: 3 # scalar
+	  template:
+	    spec:
+	      containers:  # associative list -- (name)
+	      - name: nginx
+	        image: nginx:1.7
+	        command: ['new_run.sh', 'arg1'] # non-associative list
+	      - name: sidecar2
+	        image: sidecar2:v1
+
+  > Destination
+
+	apiVersion: apps/v1
+	kind: Deployment
+	spec:
+	  replicas: 1
+	  template:
+	    spec:
+	      containers:
+	      - name: nginx
+	        image: nginx:1.6
+	        command: ['old_run.sh', 'arg0']
+	      - name: sidecar1
+	        image: sidecar1:v1
+
+  > Result
+
+	apiVersion: apps/v1
+	kind: Deployment
+	spec:
+	  replicas: 3 # scalar
+	  template:
+	    spec:
+	      containers:  # associative list -- (name)
+	      - name: nginx
+	        image: nginx:1.7
+	        command: ['new_run.sh', 'arg1'] # non-associative list
+	      - name: sidecar1
+	        image: sidecar1:v1
+	      - name: sidecar2
+	        image: sidecar2:v1

cmd/config/docs/api-conventions/merge3.md

@@ -0,0 +1,46 @@
+# Merge (3-way)
+
+  3-way merge identifies changes between an original source + updated source and merges the result
+  into a destination, overriding the destination fields where they have changed between
+  original and updated.
+
+### Resource MergeRules
+
+  - Resources present in the original and deleted from the update are deleted.
+  - Resources missing from the original and added in the update are added.
+  - Resources present only in the dest are kept without changes.
+  - Resources present in both the update and the dest have their fields merged with the destination.
+
+### Field Merge Rules
+
+  Fields are recursively merged using the following rules:
+
+  - scalars
+    - if present in either dest or updated and `null`, clear the value
+    - if unchanged between original and updated, keep dest value
+    - if changed between original and updated (added, deleted, changed), take the updated value
+
+  - non-associative lists -- lists without a merge key
+    - if present in either dest or updated and `null`, clear the value
+    - if unchanged between original and updated, keep dest value
+    - if changed between original and updated (added, deleted, changed), take the updated value
+
+  - map keys and fields -- paired by the map-key / field-name
+    - if present in either dest or updated and `null`, clear the value
+    - if present only in the dest, it keeps its value
+    - if not-present in the dest, add the delta between original-updated as a field
+    - otherwise recursively merge the value between original, updated, dest
+
+  - associative list elements -- paired by the associative key
+    - if present only in the dest, it keeps its value
+    - if not-present in the dest, add the delta between original-updated as a field
+    - otherwise recursively merge the value between original, updated, dest
+
+### Associative Keys
+
+  Associative keys are used to identify "same" elements within 2 different lists, and merge them.
+  The following fields are recognized as associative keys:
+
+  [`mountPath`, `devicePath`, `ip`, `type`, `topologyKey`, `name`, `containerPort`]
+
+  Any lists where all of the elements contain associative keys will be merged as associative lists.

cmd/config/docs/commands/cat.md

@@ -0,0 +1,21 @@
+## cat
+
+Print Resource Config from a local directory.
+
+### Synopsis
+
+Print Resource Config from a local directory.
+
+  DIR:
+    Path to local directory.
+
+### Examples
+
+    # print Resource config from a directory
+    kyaml cat my-dir/
+    
+    # wrap Resource config from a directory in an ResourceList
+    kyaml cat my-dir/ --wrap-kind ResourceList --wrap-version config.kubernetes.io/v1alpha1 --function-config fn.yaml
+    
+    # unwrap Resource config from a directory in an ResourceList
+    ... | kyaml cat

cmd/config/docs/commands/count.md

@@ -0,0 +1,15 @@
+## count
+
+Count Resources Config from a local directory.
+
+### Synopsis
+
+Count Resources Config from a local directory.
+
+  DIR:
+    Path to local directory.
+
+### Examples
+
+    # print Resource counts from a directory
+    kyaml count my-dir/

cmd/config/docs/commands/fmt.md

@@ -0,0 +1,44 @@
+## fmt
+
+Format yaml configuration files.
+
+### Synopsis
+
+Format yaml configuration files.
+
+Fmt will format input by ordering fields and unordered list items in Kubernetes
+objects.  Inputs may be directories, files or stdin, and their contents must
+include both apiVersion and kind fields.
+
+- Stdin inputs are formatted and written to stdout
+- File inputs (args) are formatted and written back to the file
+- Directory inputs (args) are walked, each encountered .yaml and .yml file
+  acts as an input
+
+For inputs which contain multiple yaml documents separated by \n---\n,
+each document will be formatted and written back to the file in the original
+order.
+
+Field ordering roughly follows the ordering defined in the source Kubernetes
+resource definitions (i.e. go structures), falling back on lexicographical
+sorting for unrecognized fields.
+
+Unordered list item ordering is defined for specific Resource types and
+field paths.
+
+- .spec.template.spec.containers (by element name)
+- .webhooks.rules.operations (by element value)
+
+### Examples
+
+	# format file1.yaml and file2.yml
+	kyaml fmt file1.yaml file2.yml
+
+	# format all *.yaml and *.yml recursively traversing directories
+	kyaml fmt my-dir/
+
+	# format kubectl output
+	kubectl get -o yaml deployments | kyaml fmt
+
+	# format kustomize output
+	kustomize build | kyaml fmt

cmd/config/docs/commands/grep.md

@@ -0,0 +1,31 @@
+## grep
+
+Search for matching Resources in a directory or from stdin
+
+### Synopsis
+
+  Search for matching Resources in a directory or from stdin.
+
+  QUERY:
+    Query to match expressed as 'path.to.field=value'.
+    Maps and fields are matched as '.field-name' or '.map-key'
+    List elements are matched as '[list-elem-field=field-value]'
+    The value to match is expressed as '=value'
+    '.' as part of a key or value can be escaped as '\.'
+
+  DIR:
+    Path to local directory.
+
+### Examples
+
+    # find Deployment Resources
+    kyaml grep "kind=Deployment" my-dir/
+    
+    # find Resources named nginx
+    kyaml grep "metadata.name=nginx" my-dir/
+    
+    # use tree to display matching Resources
+    kyaml grep "metadata.name=nginx" my-dir/ | kyaml tree
+    
+    # look for Resources matching a specific container image
+    kyaml grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kyaml tree

cmd/config/docs/commands/merge.md

@@ -0,0 +1,24 @@
+## merge
+
+Merge Resource configuration files
+
+### Synopsis
+
+Merge Resource configuration files
+
+Merge reads Kubernetes Resource yaml configuration files from stdin or sources packages and write
+the result to stdout or a destination package.
+
+Resources are merged using the Resource [apiVersion, kind, name, namespace] as the key.  If any of
+these are missing, merge will default the missing values to empty.
+
+Resources specified later are high-precedence (the source) and Resources specified
+earlier are lower-precedence (the destination).
+
+For information on merge rules, run:
+
+	kyaml docs merge
+
+### Examples
+
+    cat resources_and_patches.yaml | kyaml merge > merged_resources.yaml

cmd/config/docs/commands/run-fns.md

@@ -0,0 +1,53 @@
+## run-fns
+
+Apply config functions to Resources.
+
+### Synopsis
+
+Apply config functions to Resources.
+
+run-fns sequentially invokes all config functions in the directly, providing Resources
+in the directory as input to the first function, and writing the output of the last
+function back to the directory.
+
+The ordering of functions is determined by the order they are encountered when walking the
+directory.  To clearly specify an ordering of functions, multiple functions may be
+declared in the same file, separated by '---' (the functions will be invoked in the
+order they appear in the file).
+
+#### Arguments:
+
+  DIR:
+    Path to local directory.
+
+#### Config Functions:
+
+  Config functions are specified as Kubernetes types containing a metadata.configFn.container.image
+  field.  This fields tells run-fns how to invoke the container.
+
+  Example config function:
+
+	# in file example/fn.yaml
+	apiVersion: fn.example.com/v1beta1
+	kind: ExampleFunctionKind
+	metadata:
+	  configFn:
+	    container:
+	      # function is invoked as a container running this image
+	      image: gcr.io/example/examplefunction:v1.0.1
+	  annotations:
+	    config.kubernetes.io/local-config: "true" # tools should ignore this
+	spec:
+	  configField: configValue
+
+  In the preceding example, 'kyaml run-fns example/' would identify the function by
+  the metadata.configFn field.  It would then write all Resources in the directory to
+  a container stdin (running the gcr.io/example/examplefunction:v1.0.1 image).  It
+  would then writer the container stdout back to example/, replacing the directory
+  file contents.
+
+  See `kyaml help docs-fn` for more details on writing functions.
+
+### Examples
+
+kyaml run-fns example/

cmd/config/docs/commands/tree.md

@@ -0,0 +1,54 @@
+## tree
+
+Display Resource structure from a directory or stdin.
+
+### Synopsis
+
+Display Resource structure from a directory or stdin.
+
+kyaml tree may be used to print Resources in a directory or cluster, preserving structure
+
+Args:
+
+  DIR:
+    Path to local directory directory.
+
+Resource fields may be printed as part of the Resources by specifying the fields as flags.
+
+kyaml tree has build-in support for printing common fields, such as replicas, container images,
+container names, etc.
+
+kyaml tree supports printing arbitrary fields using the '--field' flag.
+
+By default, kyaml tree uses the directory structure for the tree structure, however when printing
+from the cluster, the Resource graph structure may be used instead.
+
+### Examples
+
+    # print Resources using directory structure
+    kyaml tree my-dir/
+    
+    # print replicas, container name, and container image and fields for Resources
+    kyaml tree my-dir --replicas --image --name
+    
+    # print all common Resource fields
+    kyaml tree my-dir/ --all
+    
+    # print the "foo"" annotation
+    kyaml tree my-dir/ --field "metadata.annotations.foo" 
+    
+    # print the "foo"" annotation
+    kubectl get all -o yaml | kyaml tree my-dir/ --structure=graph \
+      --field="status.conditions[type=Completed].status"
+    
+    # print live Resources from a cluster using graph for structure
+    kubectl get all -o yaml | kyaml tree --replicas --name --image --structure=graph
+    
+    
+    # print live Resources using graph for structure
+    kubectl get all,applications,releasetracks -o yaml | kyaml tree --structure=graph \
+      --name --image --replicas \
+      --field="status.conditions[type=Completed].status" \
+      --field="status.conditions[type=Complete].status" \
+      --field="status.conditions[type=Ready].status" \
+      --field="status.conditions[type=ContainersReady].status"