[docs] Concepts Reference

First pass at CLI documentation formatting fixes

[docs] Update README

Normalize environment server URL

Gracefully handle error when kubeconfig not present

YAML, JSON handling for prototype commands

As part of the environments feature, we want to be able to deploy to a
specific cluster given the environment's URI. We cross-check against
kubecfg for this URI's location. For fail-safe comparison, we probably
want to normalize these URIs.

We decided that this would give the users too many options. We should
limit the documentation to Jsonnet.

[docs] Add autogenerated CLI reference

Implement `registry describe` and `dep describe`

The command `dep` currently broadly allows users to inspect, use, and
search for packages. Currently, however, the name `dep` suggests that
this functionality is scoped to dependencies. Consider, for example, the
command `dep list`. A user might reasonable expect this to list all
dependencies, rather than all packages, which is what it does. Another
example is `dep search`, which actually searches all known packages, not
all known dependencies.

Hence, this commit will rename this command to simply be `pkg`.

This commit will partially resolve #38.

`registry list` and `registry describe` were designed to behave very
similarly to `prototype list` and `prototype describe`. The former
command is self-explanatory, and the second does displays some
documentation about the object in question.

This commit will implement these commands per the spec, and is a partial
fix to #38.

 Add `--help` flag to `generate` and `prototype use`

When `generate` was first implemented, we made a conscious decision to
not include the `--help` flag, so that we would not accidentally break
templates with a parameter called `help`.

But, this is unintuitive for users who want to use the `--help` flag, so
in this commit we will print the help message if (1) there is a single
command argument, and (2) it is either `--help` or `-h`.

Fixes #21.

Fix bug for duplicate environment params

Provide access to ExtCodes when the '-f' flag is provided

Use background colors for param diff

Currently, ExtCodes are only provided when the 'env' flag is present in
commands. The result is errors occuring when we run commands such as `ks
show default -f components/guestbook-ui.jsonnet`, where the params
ExtVar is needed. This commit fixes that scenario.

Foreground colors were causing conflicts with user's terminal colors.
i.e. Black text would show as invisible for users with a black terminal
background.

A bug existed where if `param set` was called for the same param twice,
a duplicate entry was created for the component. This only occured where
the component name contained a special character.

Historically, every time we've needed to write out something tabular,
we've hand-rolled an ad hoc padded row writer. Yes, in each case. Such
is #startuplife.

The third time we did this we wrote this with bugs, and so now we are
rewriting it in a general, tested function, and transitioning all places
where we call this to use this function.

Renaming environment should also rename nested .jsonnet

[bug fix] Fix optionalParam defaults

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

Currently the env directory is being renamed on `env set foo
--name=bar`, however the `foo.jsonnet` file also needs to be renamed to
`bar.jsonnet`. This commit fixes that.

De/serialize specification objects with YAML

Add optional params to prototype spec

Jsonnet handling of component names with special characters

Fixes #69.

Currently we allow users to specify prototypes using Jsonnet. At the
head of each prototype should be a comment with semi-structured
metadata, e.g.,

  // @apiVersion 0.0.1
  // @name io.ksonnet.pkg.nginx-simple
  // @description Deploys a simple, stateless nginx server with server
  // blocks (roughly equivalent
  //   to nginx virtual hosts). The nginx container is deployed using a
  //   Kubernetes deployment, and is exposed to a network with a service.
  // @param namespace string default Namespace in which to put the
  // application
  // @param name string Name to give to each of the components

Critically, some metadata about params is stored using the `@param` tag,
including name, type, and description, for pretty printing.

This commit will introduce a new param type, `@optionalParam`. This type
has a name, type, default value, and description.

It is currently not possible to specify a default value with spaces, but
this should be good enough for MVP.

Fixes #48.

Currently the structs `app.Spec`, `registry.Spec`, and `parts.Spec` are
all serialized and deserialized using JSON instead of YAML.

This commit will resolve this issue.