update docs for 0.8.0

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

cmd/registry.go

@@ -216,18 +216,21 @@ var registryAddCmd = &cobra.Command{
 	},
 
 	Long: `
-The ` + "`add`" + ` command allows custom registries to be added to your ksonnet app.
+The ` + "`add`" + ` command allows custom registries to be added to your ksonnet app,
+provided that their file structures follow the appropriate schema. *You can look
+at the ` + "`incubator`" + ` repo (https://github.com/ksonnet/parts/tree/master/incubator)
+as an example.*
 
 A registry is uniquely identified by its:
 
-1. Name
-2. Version
+1. Name (e.g. ` + "`incubator`" + `)
+2. Version (e.g. ` + "`master`" + `)
 
-Currently, only registries supporting the GitHub protocol can be added.
+Currently, only registries supporting the **GitHub protocol** can be added.
 
-All registries must specify a unique name and URI where the registry lives.
-Optionally, a version can be provided. If a version is not specified, it will
-default to  ` + "`latest`" + `.
+During creation, all registries must specify a unique name and URI where the
+registry lives. Optionally, a version can be provided (e.g. the *Github branch
+name*). If a version is not specified, it will default to ` + "`latest`" + `.
 
 
 ### Related Commands
@@ -239,7 +242,8 @@ default to  ` + "`latest`" + `.
 	Example: `# Add a registry with the name 'databases' at the uri 'github.com/example'
 ks registry add databases github.com/example
 
-# Add a registry with the name 'databases' at the uri 'github.com/example' and
-# the version 0.0.1
-ks registry add databases github.com/example --version=0.0.1`,
+# Add a registry with the name 'databases' at the uri
+# 'github.com/example/tree/master/reg' and the version (branch name) 0.0.1
+# NOTE that "0.0.1" overrides the branch name in the URI ("master")
+ks registry add databases github.com/example/tree/master/reg --version=0.0.1`,
 }

docs/cli-reference/ks_registry_add.md

@@ -6,18 +6,21 @@ Add a registry to the current ksonnet app
 
 
 
-The `add` command allows custom registries to be added to your ksonnet app.
+The `add` command allows custom registries to be added to your ksonnet app,
+provided that their file structures follow the appropriate schema. *You can look
+at the `incubator` repo (https://github.com/ksonnet/parts/tree/master/incubator)
+as an example.*
 
 A registry is uniquely identified by its:
 
-1. Name
-2. Version
+1. Name (e.g. `incubator`)
+2. Version (e.g. `master`)
 
-Currently, only registries supporting the GitHub protocol can be added.
+Currently, only registries supporting the **GitHub protocol** can be added.
 
-All registries must specify a unique name and URI where the registry lives.
-Optionally, a version can be provided. If a version is not specified, it will
-default to  `latest`.
+During creation, all registries must specify a unique name and URI where the
+registry lives. Optionally, a version can be provided (e.g. the *Github branch
+name*). If a version is not specified, it will default to `latest`.
 
 
 ### Related Commands
@@ -37,9 +40,10 @@ ks registry add <registry-name> <registry-uri>
 # Add a registry with the name 'databases' at the uri 'github.com/example'
 ks registry add databases github.com/example
 
-# Add a registry with the name 'databases' at the uri 'github.com/example' and
-# the version 0.0.1
-ks registry add databases github.com/example --version=0.0.1
+# Add a registry with the name 'databases' at the uri
+# 'github.com/example/tree/master/reg' and the version (branch name) 0.0.1
+# NOTE that "0.0.1" overrides the branch name in the URI ("master")
+ks registry add databases github.com/example/tree/master/reg --version=0.0.1
 ```
 
 ### Options

docs/concepts.md

@@ -20,6 +20,11 @@ The following diagram shows how the ksonnet framework works holistically:
 
 ![ksonnet overview diagram](/docs/img/ksonnet_overview.svg)
 
+ksonnet's package management schema can be summed up as follows:
+
+*registry* > *package* > *prototype*<br>
+**Ex:** [`incubator` repo](https://github.com/ksonnet/parts/tree/master/incubator) > [Redis library](https://github.com/ksonnet/parts/tree/master/incubator/redis) > [`redis-stateless` prototype](https://github.com/ksonnet/parts/blob/master/incubator/redis/prototypes/redis-stateless.jsonnet)
+
 ---
 
 ### Application
@@ -94,7 +99,7 @@ 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) and [*registry*](#registry) for information on downloading or sharing additional prototypes.
 
 ---
 
@@ -183,11 +188,36 @@ You can take a look at the [nginx](https://github.com/ksonnet/parts/tree/master/
 
 ### Registry
 
-Registries are essentially repositories for *packages*. (We mean registry here in the same sense that there are registries for container images). Registries are identified by a `registry.yaml` in their root that declares a list of packages.
-
-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.
+Registries are essentially repositories for *packages*. (We mean registry here in the same sense as registries for container images). Registries are identified by a `registry.yaml` in their root that declares a list of packages.
+
+You can use *default* or *custom* registries:
+
+* By **default**, ksonnet allows you do download *packages* from the [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator) registry.
+
+* You can set up your own **custom** registry with `ks registry add`, which accepts **any valid Github path**. *Note that this path needs to point a directory with the following structure:*
+
+  ```
+  .
+  ├── nginx                               // nginx package
+  │   ├── README.md
+  │   ├── nginx.libsonnet
+  │   ├── parts.yaml
+  │   └── prototypes
+  │       ├── nginx-server-block.jsonnet
+  │       ...
+  ├── redis                               // redis package
+  │   ├── README.md
+  │   ├── parts.yaml
+  │   ├── prototypes
+  │   │   ├── redis-all-features.jsonnet
+  │   │   ...
+  │   └── redis.libsonnet
+  └── registry.yaml                       // Lists all packages in the registry
+  ```
+  * For more details on the package schema, see the [*package* definition](#package).
+  * For hand-on references (e.g. for `registry.yaml` and `parts.yaml`), see the files in [`ksonnet/parts/incubator`](https://github.com/ksonnet/parts/tree/master/incubator).
+
+Use the various [`ks registry`](/docs/cli-reference/ks_registry.md) commands to list available registries, add new ones, and see what packages they contain.
 
 ---