From 8405136771a29ca99807de2a50c8064e325224ad Mon Sep 17 00:00:00 2001 From: Jessica Yao <jessica@heptio.com> Date: Thu, 30 Nov 2017 18:42:13 -0800 Subject: [PATCH] doc updates for launch Signed-off-by: Jessica Yao <jessica@heptio.com> --- README.md | 17 +++++++++-------- docs/README.md | 4 +++- docs/concepts.md | 8 ++++---- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 470da83b..458455c5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ # ksonnet +[**Official Site**](https://ksonnet.io/) + [](https://travis-ci.org/ksonnet/ksonnet) [](https://goreportcard.com/report/github.com/ksonnet/ksonnet) + *ksonnet* is a framework for writing, sharing, and deploying Kubernetes application manifests. With its CLI, you can generate a complete application from scratch in only a few commands, or manage a complex system at scale. Specifically, ksonnet allows you to: @@ -14,15 +17,13 @@ Specifically, ksonnet allows you to: All of this results in a more iterative process for developing manifests, one that can be supplemented by continuous integration (CI). -*STATUS: Development is ongoing—this tool is pre-alpha.* - ## 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` with the following command: +If you are using [Homebrew](https://brew.sh/) on macOS, you can install `ks` with the following command: ``` brew install ksonnet/tap/ks @@ -36,7 +37,7 @@ See the [releases page](https://github.com/ksonnet/ksonnet/releases) to download You can download and manually build from source by following [these instructions](/docs/build-install.md). -## Example +## Run through an example Here we provide some commands that show some basic ksonnet features in action. You can run these commands to deploy and update a basic web app UI, via a Kubernetes Service and Deployment. This app is shown below: @@ -57,7 +58,7 @@ Note that we will not be implementing the entire app in this example, so the but * *Your `$KUBECONFIG` should specify a valid `kubeconfig` file*, which points at the cluster you want to use for this demonstration. -### Example flow +### Commands You can copy and paste the commands below to deploy the web app UI: @@ -128,15 +129,15 @@ Now, even though you've made modifications to the Guestbook app and removed it f ks show default ``` -If you're still wondering how ksonnet differs from existing tools, the [tutorial](https://ksonnet-next-site.i.heptio.com/docs/tutorial) shows you how to use other ksonnet features to implement the rest of the Guestbook app (and yes, the buttons will work!). +If you're still wondering how ksonnet differs from existing tools, the [tutorial](https://ksonnet.io/docs/tutorial) shows you how to use other ksonnet features to implement the rest of the Guestbook app (and yes, the buttons will work!). ## Additional documentation ksonnet is a feature-rich framework. To learn more about how to integrate it into your workflow, check out the resources below: -* **[Tutorial](https://ksonnet-next-site.i.heptio.com/docs/tutorial)** - What can I build with ksonnet and why? This finishes the Guestbook app from the [Example](#example) above. +* **[Tutorial](https://ksonnet.io/docs/tutorial)** - What can I build with ksonnet and why? This finishes the Guestbook app from the [example](#run-through-an-example) above. -* **[Interactive tour of ksonnet](https://ksonnet-next-site.i.heptio.com/docs/tutorial/tour/welcome)** - How do `ks` commands work under the hood? +* **[Interactive tour of ksonnet](https://ksonnet.io/tour/welcome)** - How do `ks` commands work under the hood? * **[CLI Reference](/docs/cli-reference#command-line-reference)** - What ksonnet commands are available, and how do I use them? diff --git a/docs/README.md b/docs/README.md index 5c5e4a35..72f8305f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,8 @@ ## Additional documentation -While the ksonnet site updates are still pending, you can find additional documentation in this directory: +**You can view all additional documentation on the [official ksonnet site](https://ksonnet.io/).** + +If you prefer to view content in Github, you can check out the links below: * [Manually build and install](/docs/build-install.md) * [CLI reference](/docs/cli-reference#command-line-reference) diff --git a/docs/concepts.md b/docs/concepts.md index cfaf1aec..7606875b 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,6 +1,6 @@ # Concept Reference -The ksonnet framework is centered around a couple of key concepts and terms. This reference gives a brief explanation of each. To get a more tangible sense of how these concepts tie together, see the Tutorial (WIP, link pending). +The ksonnet framework is centered around a couple of key concepts and terms. This reference gives a brief explanation of each. To get a more tangible sense of how these concepts tie together, see the [Tutorial](https://ksonnet.io/docs/tutorial). * Ksonnet * [Application](#application) @@ -206,12 +206,12 @@ One of ksonnet's key features is that it allows you to write more concise manife ksonnet uses [Jsonnet](http://jsonnet.org/) to express all of your `components/` manifests (and associated configuration files, like `components/params.libsonnet`). -Jsonnet is a data templating language—for simplicity, think of it as a fancier version of JSON, one that supports features like [variables](http://jsonnet.org/docs/tutorial.html#locals) and [object concatenation](http://jsonnet.org/docs/tutorial.html#oo). If you've ever had to copy and paste large chunks of YAML or JSON manifests, Jsonnet avoids this problem! +Jsonnet is a data templating language—for simplicity, think of it as a fancier superset of JSON, one that supports features like [variables](http://jsonnet.org/docs/tutorial.html#locals) and [object concatenation](http://jsonnet.org/docs/tutorial.html#oo). If you've ever had to copy and paste large chunks of YAML or JSON manifests, Jsonnet avoids this problem! You can see how much more concise it is by comparing the same manifest, written in two different languages:  -(Note that we've omitted Jsonnet's `import` lines in this example). +*Note that we've omitted Jsonnet's `import` lines in this example.* -Jsonnet is also JSON-compatible, meaning that you can drop parts of your legacy manifests into your ksonnet manifests, without having to rewrite them all at once. +Jsonnet is also JSON-compatible, meaning that you can drop parts of your legacy manifests into your ksonnet manifests, without having to rewrite them all at once. (It is more common to have Kubernetes manifests in YAML than JSON, but there are several open-source CLI tools such as [yaml2json](https://github.com/bronze1man/yaml2json) that can do this conversion for you). -- GitLab