Merge pull request #164 from abiogenesis-now/jyao/ks-show-docs

Update ks show docs and tweak readme

README.md

@@ -18,9 +18,11 @@ All of this results in a more iterative process for developing manifests, one th
 
 ## Install
 
+The ksonnet CLI, `ks`, can be installed in three different ways. Choose the method that best matches your setup:
+
 ### Homebrew on macOS
 
-If you are using [Homebrew](https://brew.sh/) on macOS, you can easily install `ks`.
+If you are using [Homebrew](https://brew.sh/) on macOS, you can easily install `ks` with the following command:
 
 ```
 brew install ksonnet/tap/ks
@@ -153,7 +155,7 @@ Thanks for taking the time to join our community and start contributing!
 #### Before you start
 
 * Please familiarize yourself with the [Code of
-Conduct](CODE_OF_CONDUCT.md) before contributing.
+Conduct](CODE-OF-CONDUCT.md) before contributing.
 * Read the contribution guidelines in [CONTRIBUTING.md](CONTRIBUTING.md).
 * There is a [mailing list](https://groups.google.com/forum/#!forum/ksonnet) and [Slack channel](https://ksonnet.slack.com/) if you want to interact with
 other members of the community.

cmd/show.go

@@ -37,8 +37,28 @@ func init() {
 }
 
 var showCmd = &cobra.Command{
-	Use:   "show [<env>|-f <file-or-dir>]",
-	Short: "Show expanded resource definitions",
+	Use:   "show <env> [-c <component-filename>]",
+	Short: "Show expanded manifests for a specific environment.",
+	Long: `Show expanded manifests (resource definitions) for a specific environment. Jsonnet manifests,
+each defining a ksonnet component, are expanded into their JSON or YAML equivalents (YAML is the default).
+Any parameters in these Jsonnet manifests are resolved based on environment-specific values.
+
+When NO component is specified (no ` + "`-c`" + ` flag), this command expands all of the files in the ` +
+"`components/`" + ` directory into a list of resource definitions. This is the YAML version
+of what gets deployed to your cluster with ` + "`ks apply <env>`" + `.
+
+When a component IS specified via the ` + "`-c`" + ` flag, this command only expands the manifest for that
+particular component.`,
+	Example: `# Show all of the components for the 'dev' environment, in YAML
+# (In other words, expands all manifests in the components/ directory)
+ks show dev
+
+# Show a single component from the 'prod' environment, in JSON
+ks show prod -c redis -o json
+
+# Show multiple components from the 'dev' environment, in YAML
+ks show dev -c redis -c nginx-server
+`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) > 1 {
 			return fmt.Errorf("'show' takes at most a single argument, that is the name of the environment")

docs/README.md

@@ -2,6 +2,6 @@
 
 While the ksonnet site updates are still pending, you can find additional documentation in this directory:
 
-* [Manual build and install](/docs/build-install.md)
+* [Manually build and install](/docs/build-install.md)
 * [CLI reference](/docs/cli-reference#command-line-reference)
 * [Concept reference](/docs/concepts.md)

docs/build-install.md

@@ -14,12 +14,12 @@ If your ksonnet is properly installed, you should be able to run `ks --help` and
 
 ## Common issues
 
-* **Ensure that your `$GOPATH` is set appropriately.**
+* **If your error is "open /bin/ks: operation not permitted", ensure that your `$GOPATH` is set appropriately.**
   If `echo $GOPATH` results in empty output, you'll need to set it.
   If you're using macOS, trying adding the line `export GOPATH=$HOME/go` to the end of your `$HOME/.bash_profile`.
 
   Other systems may have different `$GOPATH` defaults (e.g. `/usr/local/go`), in which case you should use those instead.
-  If you get stuck, [these instructions](https://github.com/golang/go/wiki/SettingGOPATH) may help).
+  (If you get stuck, [these instructions](https://github.com/golang/go/wiki/SettingGOPATH) may help).
 
   The ksonnet Makefile assumes you have one and only one directory in your `$GOPATH`.
 
@@ -27,4 +27,4 @@ If your ksonnet is properly installed, you should be able to run `ks --help` and
   For example, try `GOPATH=<your-go-path> make install` (making sure to replace `<your-go-path>`), instead of just `make install`.
 
 * **If your error is "command not found", make sure that Go binaries are included in your $PATH**.
-  You can do this by running `PATH=$PATH:$GOPATH/bin`.
\ No newline at end of file
+  You can do this by running `PATH=$PATH:$GOPATH/bin`.

docs/cli-reference/ks.md

@@ -24,7 +24,7 @@ Synchronise Kubernetes resources with config files
 * [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet project
 * [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 resource definitions
+* [ks show](ks_show.md)	 - Show expanded manifests for a specific environment.
 * [ks validate](ks_validate.md)	 - Compare generated manifest against server OpenAPI spec
 * [ks version](ks_version.md)	 - Print version information
 

docs/cli-reference/ks_show.md

 ## ks show
 
-Show expanded resource definitions
+Show expanded manifests for a specific environment.
 
 ### Synopsis
 
 
-Show expanded resource definitions
+Show expanded manifests (resource definitions) for a specific environment. Jsonnet manifests,
+each defining a ksonnet component, are expanded into their JSON or YAML equivalents (YAML is the default).
+Any parameters in these Jsonnet manifests are resolved based on environment-specific values.
 
+When NO component is specified (no `-c` flag), this command expands all of the files in the `components/` directory into a list of resource definitions. This is the YAML version
+of what gets deployed to your cluster with `ks apply <env>`.
+
+When a component IS specified via the `-c` flag, this command only expands the manifest for that
+particular component.
+
+```
+ks show <env> [-c <component-filename>]
 ```
-ks show [<env>|-f <file-or-dir>]
+
+### Examples
+
+```
+# Show all of the components for the 'dev' environment, in YAML
+# (In other words, expands all manifests in the components/ directory)
+ks show dev
+
+# Show a single component from the 'prod' environment, in JSON
+ks show prod -c redis -o json
+
+# Show multiple components from the 'dev' environment, in YAML
+ks show dev -c redis -c nginx-server
+
 ```
 
 ### Options

docs/concepts.md

@@ -24,7 +24,7 @@ The following diagram shows how the ksonnet framework works holistically:
 
 ### Application
 
-A ksonnet application represents a well-structured directory of Kubernetes [manifests](#manifests). This directory is autogenerated by [`ksonnet init`](docs/cli-reference/ksonnet_init.md). These manifests typically tie together in some way—for example, they might collectively define a web service like the following:
+A ksonnet application represents a well-structured directory of Kubernetes [manifests](#manifests). This directory is autogenerated by [`ksonnet init`](/docs/cli-reference/ksonnet_init.md). These manifests typically tie together in some way—for example, they might collectively define a web service like the following:
 
 <p align="center">
 <img alt="ksonnet application diagram" src="/docs/img/guestbook_app.svg" height="250px">
@@ -64,7 +64,7 @@ A ksonnet *application* can be broken down into a series of discrete components:
 
 Components can be as simple as a single Kubernetes resource (e.g. a Deployment) or as complex as a complete logging stack (e.g. EFK). More concretely, a component corresponds to a Kubernetes manifest in `components/`. There are two ways to add this manifest:
 
-* Typically, **you autogenerate it** with the [`ks generate`](docs/cli-reference/ks_generate.md) command. In this case, the manifest is expressed in a language called [Jsonnet](#jsonnet).
+* Typically, **you autogenerate it** with the [`ks generate`](/docs/cli-reference/ks_generate.md) command. In this case, the manifest is expressed in a language called [Jsonnet](#jsonnet).
 
 * Alternatively, you can **manually drop in** a file. In this case, your manifest can be any one of YAML, JSON, or Jsonnet. Because all three languages are supported, *this approach allows you to introduce ksonnet to existing codebases without significant rewrites*.
 
@@ -74,7 +74,7 @@ How does the autogeneration process work? When you use `ks generate`, the compon
 <img alt="component class analogy" src="/docs/img/component_and_prototype.svg" height="180px">
 </p>
 
-All of the component files in an *app* can be deployed to a specified *environment* using [`ks apply`](docs/cli-reference/ks_apply.md).
+All of the component files in an *app* can be deployed to a specified *environment* using [`ks apply`](/docs/cli-reference/ks_apply.md).
 
 ---
 
@@ -92,13 +92,13 @@ Why is this useful? Prototypes allow you to avoid copying and pasting boilerplat
 
 ![prototype parameter component diagram](/docs/img/prototype_and_parameters.svg)
 
-Out of the box, ksonnet comes with some system prototypes (like `io.ksonnet.pkg.deployed-service`) that you can explore with the various [`ks prototype`](docs/cli-reference/ks_prototype.md) commands. See [*package*](#package) for information on downloading or sharing additional prototypes.
+Out of the box, ksonnet comes with some system prototypes (like `io.ksonnet.pkg.deployed-service`) that you can explore with the various [`ks prototype`](/docs/cli-reference/ks_prototype.md) commands. See [*package*](#package) for information on downloading or sharing additional prototypes.
 
 ---
 
 ### Parameter
 
-Parameters allow you to customize your prototypes—both at the time of their creation, and after the fact. You can use the various [`ks param`](docs/cli-reference/ks_param.md) commands to view or modify current parameters. Params can be set globally or per-environment.
+Parameters allow you to customize your prototypes—both at the time of their creation, and after the fact. You can use the various [`ks param`](/docs/cli-reference/ks_param.md) commands to view or modify current parameters. Params can be set globally or per-environment.
 
 Under the hood, the `ks param` commands update a couple of local [*Jsonnet*](#jsonnet) files, so that you always have a version-controllable representation of what you `ks apply` onto your Kubernetes cluster. These are structured as follows:
 * **App params** (`components/params.libsonnet`) — treated like defaults
@@ -159,7 +159,7 @@ A package contains:
 * **A set of related *prototypes*** (e.g. `redis-persistent`, `redis-stateless`)
 * **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*, using the various [`ks pkg`](docs/cli-reference/ks_pkg.md) commands. The CLI writes package code into the `vendor/` directory.
+Packages allow you to easily distribute and reuse code in any ksonnet *application*, using the various [`ks pkg`](/docs/cli-reference/ks_pkg.md) commands. The CLI writes package code into the `vendor/` directory.
 
 To be recognized and imported by ksonnet, packages need to follow a specific schema. See the annotated file tree below, as an example:
 ```
@@ -173,7 +173,7 @@ To be recognized and imported by ksonnet, packages need to follow a specific sch
 └── redis.libsonnet                // Helper library, includes prototype parts
 ```
 
- `parts.yaml` metadata is used to populate the output of the [`ks prototype describe`](docs/cli-reference/ks_prototype_describe.md) command. The official packages in [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator) also use `parts.yaml` to autogenerate `README.md` documentation.
+ `parts.yaml` metadata is used to populate the output of the [`ks prototype describe`](/docs/cli-reference/ks_prototype_describe.md) command. The official packages in [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator) also use `parts.yaml` to autogenerate `README.md` documentation.
 
 You can take a look at the [nginx](https://github.com/ksonnet/parts/tree/master/incubator/nginx) and [Redis](https://github.com/ksonnet/parts/tree/master/incubator/redis) packages as additional examples.
 
@@ -185,7 +185,7 @@ Registries are essentially repositories for *packages*. (We mean registry here i
 
 The ability to add new registries is under development. In the meantime, ksonnet allows you do download *packages* from the [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator) registry.
 
-Use the various [`ks registry`](docs/cli-reference/ks_registry.md) commands to see what packages are available.
+Use the various [`ks registry`](/docs/cli-reference/ks_registry.md) commands to see what packages are available.
 
 ---