edit pkg docs

Signed-off-by: Jessica Yao <jessica@heptio.com>

cmd/pkg.go

@@ -37,12 +37,43 @@ func init() {
 	pkgCmd.AddCommand(pkgInstallCmd)
 	pkgCmd.AddCommand(pkgListCmd)
 	pkgCmd.AddCommand(pkgDescribeCmd)
-	pkgInstallCmd.PersistentFlags().String(flagName, "", "Name to give the dependency")
+	pkgInstallCmd.PersistentFlags().String(flagName, "", "Name to give the dependency, to use within the ksonnet app")
+}
+
+var pkgShortDesc = map[string]string{
+	"install":     `Install a package (e.g. extra prototypes) for the current ksonnet app`,
+	"describe":    `Describe a ksonnet package and its contents`,
+	"list":        `List all packages known (downloaded or not) for the current ksonnet app`,
 }
 
 var pkgCmd = &cobra.Command{
 	Use:   "pkg",
-	Short: `Manage packages and dependencies for the current ksonnet project`,
+	Short: `Manage packages and dependencies for the current ksonnet application`,
+	Long: `
+A ksonnet package contains:
+
+* A set of prototypes, which have related output (e.g. ` + "`redis-stateless`" +`, ` + "`redis-persistent`" + `)
+* Associated helper libraries that define the prototype parts (e.g. ` + "`redis.libsonnet`" + `)
+
+Packages allow you to easily distribute and reuse code in any ksonnet application.
+Packages come from registries, such as Github repositories. (For more info, see
+` + "`ks registry --help`" + `).
+
+To be recognized and imported by ksonnet, packages need to follow a specific schema.
+See the annotated file tree below, as an example:
+
+` + "```" + `
+.
+├── README.md                      // Human-readable description of the package
+├── parts.yaml                     // Provides metadata about the package
+├── prototypes                     // Can be imported and used to generate components
+│   ├── redis-all-features.jsonnet
+│   ├── redis-persistent.jsonnet
+│   └── redis-stateless.jsonnet
+└── redis.libsonnet                // Helper library, includes prototype parts
+` + "```" + `
+---
+`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 0 {
 			return fmt.Errorf("%s is not a valid subcommand\n\n%s", strings.Join(args, " "), cmd.UsageString())
@@ -53,7 +84,7 @@ var pkgCmd = &cobra.Command{
 
 var pkgInstallCmd = &cobra.Command{
 	Use:     "install <registry>/<library>@<version>",
-	Short:   `Install a package as a dependency in the current ksonnet application`,
+	Short:   pkgShortDesc["install"],
 	Aliases: []string{"get"},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 1 {
@@ -83,36 +114,33 @@ var pkgInstallCmd = &cobra.Command{
 
 		return nil
 	},
-	Long: `Cache a ksonnet library locally, and make it available for use in the current
-ksonnet project. This particularly means that we record enough information in
-` + " `app.yaml` " + `for new users to retrieve the dependency after a fresh clone of the
-app repository.
-
-For example, inside a ksonnet application directory, run:
-
-    ks pkg install incubator/nginx@v0.1
-
-This can then be referenced in a source file in the ksonnet project:
-
-    local nginx = import "kspkg://nginx";
-
-By default, ksonnet knows about two registries: incubator and stable, which are
-the release channels for official ksonnet libraries. Additional registries can
-be added with the` + " `ks registry` " + `command.
-
-Note that multiple versions of the same ksonnet library can be cached and used
-in the same project, by explicitly passing in the` + " `--name` " + `flag. For example:
-
-    ks pkg install incubator/nginx@v0.1 --name nginxv1
-    ks pkg install incubator/nginx@v0.2 --name nginxv2
-
-With these commands, a user can` + " `import \"kspkg://nginxv1\"` " + `, and
-` + " `import \"kspkg://nginxv2\"` " + `with no conflict.`,
+	Long: `
+The ` + "`install`" + ` command caches a ksonnet library locally, and make it available
+for use in the current ksonnet application. Enough info and metadata is recorded in
+` + " `app.yaml` " + `that new users can retrieve the dependency after a fresh clone of this app.
+
+The library itself needs to be located in a registry (e.g. Github repo). By default,
+ksonnet knows about two registries: *incubator* and *stable*, which are the release
+channels for official ksonnet libraries.
+
+### Related Commands
+
+* ` + "`ks pkg list` " + `— ` + pkgShortDesc["list"] + `
+* ` + "`ks prototype list` " + `— ` + protoShortDesc["list"] + `
+
+### Syntax
+`,
+  Example: `
+# Install an nginx dependency, based on the 'master' branch.
+# In a ksonnet source file, this can be referenced as:
+#     local nginx = import "incubator/nginx/nginx.libsonnet";
+ks pkg install incubator/nginx@master
+`,
 }
 
 var pkgDescribeCmd = &cobra.Command{
 	Use:   "describe [<registry-name>/]<package-name>",
-	Short: `Describe a ksonnet package`,
+	Short: pkgShortDesc["describe"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 1 {
 			return fmt.Errorf("Command 'pkg describe' requires a package name\n\n%s", cmd.UsageString())
@@ -165,13 +193,27 @@ var pkgDescribeCmd = &cobra.Command{
 		return nil
 	},
 
-	Long: `Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some 'registry-name'.`,
+	Long: `
+The ` + "`describe`" + ` command outputs documentation for a package that is available
+(e.g. downloaded) in the current ksonnet application. (This must belong to an already
+known ` + "`<registry-name>`" + ` like *incubator*). The output includes:
+
+1. The library name
+2. A brief description provided by the library authors
+3. A list of available prototypes provided by the library
+
+### Related Commands
+
+* ` + "`ks prototype describe` " + `— ` + protoShortDesc["describe"] + `
+* ` + "`ks generate` " + `— ` + protoShortDesc["use"] + `
+
+### Syntax
+`,
 }
 
 var pkgListCmd = &cobra.Command{
 	Use:   "list",
-	Short: `Lists information about all dependencies known to the current ksonnet app`,
+	Short: pkgShortDesc["list"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		const (
 			nameHeader      = "NAME"
@@ -230,6 +272,22 @@ var pkgListCmd = &cobra.Command{
 		fmt.Print(formatted)
 		return nil
 	},
+	Long: `
+The ` + "`list`" + ` command outputs a table that describes all *known* packages (not
+necessarily downloaded, but available from existing registries). This includes
+the following info:
+
+1. Library name
+2. Registry name
+3. Installed status — this is indicated by an asterisk
+
+### Related Commands
+
+* ` + "`ks pkg install` " + `— ` + pkgShortDesc["install"] + `
+* ` + "`ks pkg describe` " + `— ` + pkgShortDesc["describe"] + `
+
+### Syntax
+`,
 }
 
 func parsePkgSpec(spec string) (registry, libID string, err error) {

cmd/prototype.go

@@ -125,7 +125,7 @@ from the *incubator* registry.
 * ` + "`ks prototype describe` " + `— ` + protoShortDesc["describe"] + `
 * ` + "`ks prototype preview` " + `— ` + protoShortDesc["preview"] + `
 * ` + "`ks prototype use` " + `— ` + protoShortDesc["use"] + `
-* ` + "`ks pkg install` " + `— Install more prototypes (from external packages)
+* ` + "`ks pkg install` " + pkgShortDesc["install"] + `
 
 ### Syntax
 `,

docs/cli-reference/ks.md

@@ -26,7 +26,7 @@ application configuration to remote clusters.
 * [ks generate](ks_generate.md)	 - Use the specified prototype to generate a component manifest
 * [ks init](ks_init.md)	 - Initialize a ksonnet application
 * [ks param](ks_param.md)	 - Manage ksonnet parameters for components and environments
-* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet project
+* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet application
 * [ks prototype](ks_prototype.md)	 - Instantiate, inspect, and get examples for ksonnet prototypes
 * [ks registry](ks_registry.md)	 - Manage registries for current project
 * [ks show](ks_show.md)	 - Show expanded manifests for a specific environment.

docs/cli-reference/ks_param_diff.md

@@ -21,7 +21,7 @@ is supported via a component flag.
 
 
 ```
-ks param diff <env1> <env2>
+ks param diff <env1> <env2> [--component <component-name>]
 ```
 
 ### Examples

docs/cli-reference/ks_pkg.md

 ## ks pkg
 
-Manage packages and dependencies for the current ksonnet project
+Manage packages and dependencies for the current ksonnet application
 
 ### Synopsis
 
 
-Manage packages and dependencies for the current ksonnet project
+
+A ksonnet package contains:
+
+* A set of prototypes, which have related output (e.g. `redis-stateless`, `redis-persistent`)
+* Associated helper libraries that define the prototype parts (e.g. `redis.libsonnet`)
+
+Packages allow you to easily distribute and reuse code in any ksonnet application.
+Packages come from registries, such as Github repositories. (For more info, see
+`ks registry --help`).
+
+To be recognized and imported by ksonnet, packages need to follow a specific schema.
+See the annotated file tree below, as an example:
+
+```
+.
+├── README.md                      // Human-readable description of the package
+├── parts.yaml                     // Provides metadata about the package
+├── prototypes                     // Can be imported and used to generate components
+│   ├── redis-all-features.jsonnet
+│   ├── redis-persistent.jsonnet
+│   └── redis-stateless.jsonnet
+└── redis.libsonnet                // Helper library, includes prototype parts
+```
+---
+
 
 ```
 ks pkg
@@ -19,7 +43,7 @@ ks pkg
 
 ### SEE ALSO
 * [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
-* [ks pkg describe](ks_pkg_describe.md)	 - Describe a ksonnet package
-* [ks pkg install](ks_pkg_install.md)	 - Install a package as a dependency in the current ksonnet application
-* [ks pkg list](ks_pkg_list.md)	 - Lists information about all dependencies known to the current ksonnet app
+* [ks pkg describe](ks_pkg_describe.md)	 - Describe a ksonnet package and its contents
+* [ks pkg install](ks_pkg_install.md)	 - Install a package (e.g. extra prototypes) for the current ksonnet app
+* [ks pkg list](ks_pkg_list.md)	 - List all packages known (downloaded or not) for the current ksonnet app
 

docs/cli-reference/ks_pkg_describe.md

 ## ks pkg describe
 
-Describe a ksonnet package
+Describe a ksonnet package and its contents
 
 ### Synopsis
 
 
-Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some 'registry-name'.
+
+The `describe` command outputs documentation for a package that is available
+(e.g. downloaded) in the current ksonnet application. (This must belong to an already
+known `<registry-name>` like *incubator*). The output includes:
+
+1. The library name
+2. A brief description provided by the library authors
+3. A list of available prototypes provided by the library
+
+### Related Commands
+
+* `ks prototype describe` — See more info about a prototype's output and usage
+* `ks generate` — Use the specified prototype to generate a component manifest
+
+### Syntax
+
 
 ```
 ks pkg describe [<registry-name>/]<package-name>
@@ -19,5 +33,5 @@ ks pkg describe [<registry-name>/]<package-name>
 ```
 
 ### SEE ALSO
-* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet project
+* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet application
 

docs/cli-reference/ks_pkg_install.md

 ## ks pkg install
 
-Install a package as a dependency in the current ksonnet application
+Install a package (e.g. extra prototypes) for the current ksonnet app
 
 ### Synopsis
 
 
-Cache a ksonnet library locally, and make it available for use in the current
-ksonnet project. This particularly means that we record enough information in
- `app.yaml` for new users to retrieve the dependency after a fresh clone of the
-app repository.
 
-For example, inside a ksonnet application directory, run:
+The `install` command caches a ksonnet library locally, and make it available
+for use in the current ksonnet application. Enough info and metadata is recorded in
+ `app.yaml` that new users can retrieve the dependency after a fresh clone of this app.
 
-    ks pkg install incubator/nginx@v0.1
+The library itself needs to be located in a registry (e.g. Github repo). By default,
+ksonnet knows about two registries: *incubator* and *stable*, which are the release
+channels for official ksonnet libraries.
 
-This can then be referenced in a source file in the ksonnet project:
+### Related Commands
 
-    local nginx = import "kspkg://nginx";
+* `ks pkg list` — List all packages known (downloaded or not) for the current ksonnet app
+* `ks prototype list` — List all locally available ksonnet prototypes
 
-By default, ksonnet knows about two registries: incubator and stable, which are
-the release channels for official ksonnet libraries. Additional registries can
-be added with the `ks registry` command.
+### Syntax
 
-Note that multiple versions of the same ksonnet library can be cached and used
-in the same project, by explicitly passing in the `--name` flag. For example:
 
-    ks pkg install incubator/nginx@v0.1 --name nginxv1
-    ks pkg install incubator/nginx@v0.2 --name nginxv2
+```
+ks pkg install <registry>/<library>@<version>
+```
 
-With these commands, a user can `import "kspkg://nginxv1"` , and
- `import "kspkg://nginxv2"` with no conflict.
+### Examples
 
 ```
-ks pkg install <registry>/<library>@<version>
+
+# Install an nginx dependency, based on the 'master' branch.
+# In a ksonnet source file, this can be referenced as:
+#     local nginx = import "incubator/nginx/nginx.libsonnet";
+ks pkg install incubator/nginx@master
+
 ```
 
 ### Options
 
 ```
-      --name string   Name to give the dependency
+      --name string   Name to give the dependency, to use within the ksonnet app
 ```
 
 ### Options inherited from parent commands
@@ -48,5 +50,5 @@ ks pkg install <registry>/<library>@<version>
 ```
 
 ### SEE ALSO
-* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet project
+* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet application
 

docs/cli-reference/ks_pkg_list.md

 ## ks pkg list
 
-Lists information about all dependencies known to the current ksonnet app
+List all packages known (downloaded or not) for the current ksonnet app
 
 ### Synopsis
 
 
-Lists information about all dependencies known to the current ksonnet app
+
+The `list` command outputs a table that describes all *known* packages (not
+necessarily downloaded, but available from existing registries). This includes
+the following info:
+
+1. Library name
+2. Registry name
+3. Installed status — this is indicated by an asterisk
+
+### Related Commands
+
+* `ks pkg install` — Install a package (e.g. extra prototypes) for the current ksonnet app
+* `ks pkg describe` — Describe a ksonnet package and its contents
+
+### Syntax
+
 
 ```
 ks pkg list
@@ -18,5 +33,5 @@ ks pkg list
 ```
 
 ### SEE ALSO
-* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet project
+* [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet application
 

docs/cli-reference/ks_prototype_list.md

@@ -19,7 +19,7 @@ from the *incubator* registry.
 * `ks prototype describe` — See more info about a prototype's output and usage
 * `ks prototype preview` — Preview a prototype's output without creating a component (stdout)
 * `ks prototype use` — Use the specified prototype to generate a component manifest
-* `ks pkg install` — Install more prototypes (from external packages)
+* `ks pkg install` Install a package (e.g. extra prototypes) for the current ksonnet app
 
 ### Syntax