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

No new documentation added.

cmd/config/cmddocs/commands/docs.go

@@ -0,0 +1,219 @@
+// Copyright 2019 The Kubernetes Authors.
+// SPDX-License-Identifier: Apache-2.0
+
+// Code generated by "mdtogo"; DO NOT EDIT.
+package commands
+
+var CatShort = `Print Resource Config from a local directory.`
+var CatLong = `
+Print Resource Config from a local directory.
+
+  DIR:
+    Path to local directory.
+`
+var CatExamples = `
+    # 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`
+
+var CountShort = `Count Resources Config from a local directory.`
+var CountLong = `
+Count Resources Config from a local directory.
+
+  DIR:
+    Path to local directory.
+`
+var CountExamples = `
+    # print Resource counts from a directory
+    kyaml count my-dir/`
+
+var FmtShort = `Format yaml configuration files.`
+var FmtLong = `
+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)
+`
+var FmtExamples = `
+	# 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`
+
+var GrepShort = `Search for matching Resources in a directory or from stdin`
+var GrepLong = `
+  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.
+`
+var GrepExamples = `
+    # 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`
+
+var MergeShort = `Merge Resource configuration files`
+var MergeLong = `
+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
+`
+var MergeExamples = `
+    cat resources_and_patches.yaml | kyaml merge > merged_resources.yaml`
+
+var RunFnsShort = `Apply config functions to Resources.`
+var RunFnsLong = `
+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.
+`
+var RunFnsExamples = `
+kyaml run-fns example/`
+
+var TreeShort = `Display Resource structure from a directory or stdin.`
+var TreeLong = `
+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.
+`
+var TreeExamples = `
+    # 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"`