`fn doc` output and documentation

[frankfarzan]

1. It's not documented in kpt.dev
2. Output includes usage

$ kpt fn doc --image gcr.io/kpt-fn/kubeval:v0.1
usage: FUNC [-h] [-i INPUT] [-o OUTPUT] [-f FUNCTION_CONFIG]
            [-d [FUNCTION_CONFIG_LITERAL [FUNCTION_CONFIG_LITERAL ...]]]
            [--json] [--log-to-stderr]

Validates configuration using kubeval.

If neither schema_location nor additional_schema_locations is provided, we
will use the baked-in schemas. Otherwise, we will try to download the schemas.

Configured using a ConfigMap with the following keys, all of which are optional:
schema_location: The base URL used to download schemas.
additional_schema_locations: List of secondary base URLs used to download
  schemas.  These URLs will be used if the URL specified by schema_location
  did not have the required schema.  By default, there are no secondary URLs,
  and only the primary base URL will be used.
ignore_missing_schemas: Skip validation for resource definitions without a
  schema.  If omitted, a default value of false will be assumed.
skip_kinds: Comma-separated list of case-sensitive kinds to skip when
  validating against schemas.  If omitted, no kinds will be skipped.
strict: Disallow additional properties not in schema.  If omitted, a default
  value of false will be assumed.

Example invocations:

  1. Using regular files for input and output:

    $ FUNC -i in.yaml -o out.yaml

  2. Print output to stdout:

    $ FUNC -i in.yaml

  3. Using redirection:

    $ FUNC < in.yaml > out.yaml

  4. Using pipes:

    $ cat in.yaml | FUNC | cat

  5. Using /dev/null for source/sink functions:

    $ FUNC -i /dev/null -o /dev/null

  6. Specifying 'functionConfig' as a separate file:

    $ cat in.yaml | FUNC -f fc.yaml

    If the input contains 'functionConfig' field, it will be ignored.

  7. Specifying 'functionConfig' using key/value literals:

    $ cat in.yaml | FUNC -d key1=value1 -d key2=value2

    This is a convenient way to populate the functionConfig if it's a ConfigMap.

Optional arguments:
  -h, --help            Show this help message and exit.
  -i INPUT, --input INPUT
                        Path to the input file (if not reading from stdin)
  -o OUTPUT, --output OUTPUT
                        Path to the output file (if not writing to stdout)
  -f FUNCTION_CONFIG, --function-config FUNCTION_CONFIG
                        Path to the function configuration file. If specified, ignores "functionConfig" field in the input
  -d [FUNCTION_CONFIG_LITERAL [FUNCTION_CONFIG_LITERAL ...]], --function-config-literal [FUNCTION_CONFIG_LITERAL [FUNCTION_CONFIG_LITERAL ...]]
                        Specify a key and literal value (i.e. mykey=somevalue) to populate a ConfigMap instead of
                        specifying a file using --function-config.
                        Use this ONLY if the function accepts a ConfigMap.
  --json                Input and output files are in JSON instead of YAML
  --log-to-stderr       Emit structured results to stderr in addition to setting".results" field in stdout
Remember, everything here is CONFIDENTIAL unless specifically stated otherwise.

© 2020 Google LLC. All Rights Reserved.

[phanimarupaka]

@frankfarzan @droot We should also have a way to list the available functions

$ kpt fn doc
Here are the list of available kpt functions
gcr.io/kpt-fn/apply-setters:v0.1
gcr.io/kpt-fn/apply-setters:v0.2
gcr.io/kpt-fn/set-namespace:v0.1
...

$ kpt fn doc --image gcr.io/kpt-fn/apply-setters:v0.1
Display the usage documentation(similar to the one in issue description.)

cc @bgrant0607

[bgrant0607]

+1 to listing available functions for each registered catalog (I assume multiple catalogs will happen as soon as others start to write functions).

Being able to filter according to relevant functions would be awesome, too.

As we move functionality out of inline parameters and template code into functions, users need to be able to discover applicable functions they could use on a given package containing a particular set of resource types. For instance, if there were a function to set Gatekeeper (https://open-policy-agent.github.io/gatekeeper/website/docs/violations/#dry-run-enforcement-action) constraint common attributes such as enforcementAction, excludedNamespaces, etc., we would like to recommend it for a package containing pod security constraints (https://github.com/open-policy-agent/gatekeeper-library/tree/master/library/pod-security-policy).

[morgante]

+1 to highlighting relevant functions. For example, a set-project function should be highlighted when interacting with a KCC package but is useless otherwise.

[frankfarzan]

I suggest filing a separate issue for function discovery. This issue is specifically about the doc command that shows the help message for a given function which is orthogonal to this.

[frankfarzan]

Filed https://github.com/GoogleContainerTools/kpt/issues/2333 to track function discovery