fn sink and source reference docs (kptdev#2013)

site/reference/fn/eval/README.md

@@ -22,28 +22,37 @@ Refer to the [Imperative Function Execution] for detailed overview.
 
 <!--mdtogo:Long-->
 
-```shell
+```
 kpt fn eval [DIR|-] [flags] [-- fn-args]
 ```
 
 #### Args
 
-```shell
+```
 DIR|-:
   Path to the local directory containing resources. Defaults to the current
   working directory. Using '-' as the directory path will cause `eval` to
-  read resources from `stdin` and write the output to `stdout`.
+  read resources from `stdin` and write the output to `stdout`. When resources are
+  read from `stdin`, they must be in one of the following input formats:
+
+  1. Multi object YAML where resources are separated by `---`.
+
+  2. `Function Specification` wire format where resources are wrapped in an object
+     of kind ResourceList.
+ 
+  If the output is written to `stdout`, resources are written in multi object YAML
+  format where resources are separated by `---`.
 ```
 
-```shell
+```
 fn-args:
   function arguments to be provided as input to the function. These must be
   provided in the `key=value` format and come after the separator `--`.
 ```
 
 #### Flags
 
-```shell
+```
 --as-current-user:
   Use the `uid` and `gid` of the kpt process for container function execution.
   By default, container function is executed as `nobody` user. You may want to use
@@ -98,55 +107,55 @@ fn-args:
 ## Examples
 <!--mdtogo:Examples-->
 
-```shell
+```
 # execute container my-fn on the resources in DIR directory and
 # write output back to DIR
 $ kpt fn eval DIR --image gcr.io/example.com/my-fn
 ```
 
-```shell
+```
 # execute container my-fn on the resources in DIR directory with
 # `functionConfig` my-fn-config
 $ kpt fn eval DIR --image gcr.io/example.com/my-fn --fn-config my-fn-config
 ```
 
-```shell
+```
 # execute container my-fn with an input ConfigMap containing `data: {foo: bar}`
 $ kpt fn eval DIR --image gcr.io/example.com/my-fn:v1.0.0 -- foo=bar
 ```
 
-```shell
+```
 # execute executable my-fn on the resources in DIR directory and
 # write output back to DIR
 $ kpt fn eval DIR --exec-path ./my-fn
 ```
 
-```shell
+```
 # execute container my-fn on the resources in DIR directory,
 # save structured results in /tmp/my-results dir and write output back to DIR
 $ kpt fn eval DIR --image gcr.io/example.com/my-fn --results-dir /tmp/my-results-dir
 ```
 
-```shell
+```
 # execute container my-fn on the resources in DIR directory with network access enabled,
 # and write output back to DIR
 $ kpt fn eval DIR --image gcr.io/example.com/my-fn --network 
 ```
 
-```shell
+```
 # execute container my-fn on the resource in DIR and export KUBECONFIG
 # and foo environment variable
 $ kpt fn eval DIR --image gcr.io/example.com/my-fn --env KUBECONFIG -e foo=bar
 ```
 
-```shell
+```
 # execute kubeval function by mounting schema from a local directory on wordpress package
 $ kpt fn eval --image gcr.io/kpt-fn/kubeval:v0.1 \
   --mount type=bind,src="/path/to/schema-dir",dst=/schema-dir \
   --as-current-user wordpress -- additional_schema_locations=/schema-dir
 ```
 
-```shell
+```
 # chaining functions using the unix pipe to set namespace and set labels on
 # wordpress package
 $ kpt fn source wordpress \
@@ -157,4 +166,5 @@ $ kpt fn source wordpress \
 <!--mdtogo-->
 
 [docker volumes]: https://docs.docker.com/storage/volumes/
-[Imperative Function Execution]: /book/04-using-functions/02-imperative-function-execution
+[Imperative Function Execution]: /book/04-using-functions/02-imperative-function-execution
+[Function Specification]: /book/05-developing-functions/02-function-specification

site/reference/fn/sink/README.md

@@ -1,51 +1,52 @@
 ---
-title: "Sink"
+title: "`sink`"
 linkTitle: "sink"
 type: docs
 description: >
-   Specify a directory as an output sink package
+   Write resources to a local directory
 ---
 
 <!--mdtogo:Short
-    Specify a directory as an output sink package
+   Write resources to a local directory
 -->
 
-Implements a [sink function] by reading STDIN and writing configuration.
+`sink` reads resources from `stdin` and writes them to a local directory.
+Resources must be in one of the following input formats:
 
-Sink will not prune / delete files for delete resources because it only knows
-about files for which it sees input resources.
+  1. Multi object YAML where resources are separated by `---`.
 
-### Examples
-
-<!--mdtogo:Examples-->
+  2. `Function Specification` wire format where resources are wrapped in an object
+     of kind ResourceList.
 
-```shell
-# run a function using explicit sources and sinks
-kpt fn source DIR/ |
-  kpt fn run --image gcr.io/example.com/my-fn |
-  kpt fn sink DIR/
-```
-
-<!--mdtogo-->
+`sink` is useful for chaining functions using Unix pipe. For more details,
+refer to [Chaining functions].
 
 ### Synopsis
 
 <!--mdtogo:Long-->
 
-```shell
-kpt fn sink [DIR]
+```
+kpt fn sink DIR [flags]
 
 DIR:
-  Path to a package directory.  Defaults to stdout if unspecified.
+  Path to a local directory to write resources to. Directory must exist.
 ```
 
 <!--mdtogo-->
 
-### Next Steps
+### Examples
+
+<!--mdtogo:Examples-->
 
-- Learn about [functions concepts] like sources, sinks, and pipelines.
-- See more examples of sink functions in the functions [catalog].
+```
+# read resources from DIR directory, execute my-fn on them and write the
+# output to DIR directory.
+$ kpt fn source DIR |
+  kpt fn eval --image gcr.io/example.com/my-fn - |
+  kpt fn sink DIR
+```
+
+<!--mdtogo-->
 
-[sink function]: https://kpt.dev#todo
-[functions concepts]: /book/02-concepts/02-functions
-[catalog]: https://kpt.dev#todo
+[Chaining functions]: /book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe
+[Function Specification]: /book/05-developing-functions/02-function-specification

site/reference/fn/source/README.md

@@ -1,71 +1,64 @@
 ---
-title: "Source"
+title: "`source`"
 linkTitle: "source"
 type: docs
 description: >
-   Specify a directory as an input source package
+   Source resources from a local directory
 ---
 
 <!--mdtogo:Short
-    Specify a directory as an input source package
+    Source resources from a local directory
 -->
 
-Implements a [source function] by reading configuration and writing to STDOUT.
+`source` reads resources from a local directory and writes them in [Function Specification]
+wire format to `stdout`. The output of the `source` can be pipe'd to commands
+such as `kpt fn eval` that accepts [Function Specification] wire format. `source`
+is useful for chaining functions using Unix pipe. For more details, refer to
+[Chaining functions] and [Function Specification].
 
-### Examples
+### Synopsis
 
-{{% hide %}}
+<!--mdtogo:Long-->
 
-<!-- @makeWorkplace @verifyExamples-->
 ```
-# Set up workspace for the test.
-TEST_HOME=$(mktemp -d)
-cd $TEST_HOME
+kpt fn source [DIR] [flags]
 ```
 
-<!-- @fetchPackage @verifyExamples-->
-```shell
-export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git
-kpt pkg get $SRC_REPO/package-examples/helloworld-set@next DIR/
-```
+#### Args
 
-{{% /hide %}}
+```
+DIR:
+  Path to the local directory containing resources. Defaults to the current
+  working directory.
+```
 
-<!--mdtogo:Examples-->
+#### Flags
 
-<!-- @fnSource @verifyExamples-->
-```shell
-# print to stdout configuration from DIR/ formatted as an input source
-kpt fn source DIR/
 ```
+--fn-config:
+  Path to the file containing `functionConfig`.
 
-```shell
-# run a function using explicit sources and sinks
-kpt fn source DIR/ |
-  kpt fn run --image gcr.io/example.com/my-fn |
-  kpt fn sink DIR/
 ```
 
 <!--mdtogo-->
+### Examples
 
-### Synopsis
-
-<!--mdtogo:Long-->
+<!--mdtogo:Examples-->
 
-```shell
-kpt fn source [DIR...]
+```
+# read resources from DIR directory and write the output on stdout.
+$ kpt fn source DIR
+```
 
-DIR:
-  Path to a package directory.  Defaults to stdin if unspecified.
+```
+# read resources from DIR directory, execute my-fn on them and write the
+# output to DIR directory.
+$ kpt fn source DIR |
+  kpt fn eval --image gcr.io/example.com/my-fn - |
+  kpt fn sink DIR
 ```
 
 <!--mdtogo-->
 
-### Next Steps
-
-- Learn about [functions concepts] like sources, sinks, and pipelines.
-- See more examples of source functions in the functions [catalog].
-
-[source function]: https://kpt.dev#todo
-[functions concepts]: /book/02-concepts/02-functions
-[catalog]: https://kpt.dev#todo
+[Chaining functions]: /book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe
+[Function Specification]: /book/05-developing-functions/02-function-specification

thirdparty/cmdconfig/commands/cmdsink/cmdsink.go

@@ -14,9 +14,9 @@ import (
 func GetSinkRunner(name string) *SinkRunner {
 	r := &SinkRunner{}
 	c := &cobra.Command{
-		Use:     "sink [DIR]",
+		Use:     "sink DIR [flags]",
 		Short:   fndocs.SinkShort,
-		Long:    fndocs.SinkLong,
+		Long:    fndocs.SinkShort + "\n" + fndocs.SinkLong,
 		Example: fndocs.SinkExamples,
 		RunE:    r.runE,
 		Args:    cobra.MinimumNArgs(1),