more documentation review

README.md

@@ -1,49 +1,103 @@
 # Koki Short
-API friendly Kubernetes resources to user-friendly syntax
+
+Manageable Kubernetes manifests through composable, reusable syntax
 
 ## Motivation
-The description format for Kubernetes manifests, as it stands today, is verbose and unintuitive. It has anecdotally been 
- - Time consuming to use it to create Kubernetes resources
- - Error prone to get it right the first time
- - Requires constant referral to documentation
- - Difficult to maintain, read or reuse.  
+The description format for Kubernetes manifests, as it stands today, is verbose and unintuitive. Anecdotally, it has been:
+
+ - Time consuming to write
+ - Error-prone, hard to get right without referring to documentation
+ - Difficult to maintain, read, and reuse
 
-For eg. denoting that a pod runs on host with label `k8s.io/failure-domain=us-east-1`, here is the current syntax:
+e.g. In order to create a simple nginx pod that runs on any host in region `us-east1` or `us-east2`, here is the Kubernetes native syntax:
 
 ```yaml
-affinity:
-  nodeAffinity:
-    requiredDuringSchedulingIgnoredDuringExecution:
-     - matchExpressions:
-        - key: k8s.io/failure-domain
-          operator: In
-          value: us-east1
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+  labels:
+    app: nginx
+spec:
+  containers:
+  - name: nginx_container
+    image: nginx:latest
+  affinity:
+    nodeAffinity:
+      requiredDuringSchedulingIgnoredDuringExecution:
+      	nodeSelectorTerms:
+        - matchExpressions:
+          - key: k8s.io/failure-domain
+            operator: In
+            values: 
+            - us-east1
+        - matchExpressions:
+          - key: k8s.io/failure-domain
+            operator: In
+            value:
+            - us-east2
 ```
-The Short format is designed to be user friendly, intuitive, reusable and maintainable. The same affinity syntax in Short looks like
+
+The Short format is designed to be user friendly, intuitive, reusable, and maintainable. The same pod in Short syntax looks like
 
 ```yaml
-affinity:
- - node: k8s.io/failure-domain=us-east1
+pod:
+  name: nginx
+  labels:
+    app: nginx
+  containers:
+  - name: nginx
+    image: nginx:latest
+  affinity:
+  - node: k8s.io/failure-domain=us-east1,us-east2
 ```
-The approach we have followed behind this opinionated syntax is to reframe the Kubernetes syntax to one that is operator friendly without losing any information. 
 
-Since we do not throw away any information during the transformations, users can freely round trip back and forth between Short syntax and Kubernetes syntax.
+Our approach is to reframe Kubernetes manifests in an operator-friendly syntax without sacrificing expressiveness.
+
+Koki Short can transform Kubernetes syntax into Short and Short syntax back into Kubernetes. No information is lost in either direction.
 
-For more information on Koki Short transformations, please refer to [docs](http://docs.koki.io/short)
+For more information on Koki Short transformations, please refer to [Resources.](https://docs.koki.io/short/resources)
 
 ## Modular and Reusable
 
-Koki Short introduces the concept of modules, which are reusable collections of Short resources. Any resource can be reused multiple times in other resources and linked resources can be managed as one unit on the Koki platform. 
+Koki Short introduces the concept of modules, which are reusable collections of Short resources. Any resource can be reused multiple times in other resources and linked resources can be managed as a single unit on the Koki platform. 
+
+Any valid koki resource object can be reused. This includes subtypes of top-level resource types. For example, here's module called `pod-affinity-us-east-1.yaml`:
+
+```yaml
+exports:
+- default: node affinity for us-east-1
+  value:
+  - node: k8s.io/failure-domain=us-east-1
+```
+
+This affinity value can be reused in any pod spec:
 
-More on this will be available as soon as it is implemented. This is in the roadmap right now. 
+```yaml
+imports:
+- affinity: pod-affinity-us-east-1.yaml
+exports:
+- default: an nginx pod
+  value:
+    pod:
+      name: nginx
+      labels:
+        app: nginx
+      containers:
+      - name: nginx
+        image: nginx-latest
+      affinity: ${affinity}  # re-use the affinity resource here
+```
+
+For more information on Koki Modules, please refer to [Modules.](https://docs.koki.io/modules)
 
 ## Getting started
 
-In order to start using Short, simply download the binary from the [releases page](https://github.com/koki/short/releases), and then you can start using it.
+In order to start using Short, simply download the binary from the [releases page](https://github.com/koki/short/releases).
 
 ```sh
 
-#start with an existing Kubernetes manifest file
+#start with any existing Kubernetes manifest file
 $$ cat kube_manifest.yaml
 apiVersion: v1
 kind: Pod
@@ -80,7 +134,7 @@ spec:
           memory: 512m
 
      
-#convert an existing Kubernetes manifest into a Short syntax representation, just run
+#convert Kubernetes manifest into a Short syntax representation
 $$ short -f kube_manifest.yaml
 pod:
   name: podName
@@ -102,7 +156,7 @@ pod:
         name: service
 
 
-#specify json input, or multi document yaml 
+#input can be json or yaml
 $$ short -f kube_manifest.json -f kube_manifest2.yaml -f kube_multi_manifest.yaml
 
 #stream input
@@ -113,11 +167,10 @@ $$ short -k -f koki_spec.yaml
 
 #-k flag denotes that it should output Kubernetes manifest
 
-#find out how koki transforms a particular resource type
-short man v1/pod
-
 ```
 
+For more information, refer to our [getting started guide.](https://docs.koki.io/user-guide#getting-started)
+
 ## Contribute
 Koki is completely open source community driven, including the roadmaps, planning, and implementation. We encourage everyone to help us make Kubernetes manifests more manageable. We welcome Issues, Pull Requests and participation in our [weekly meetings]().
 
@@ -126,9 +179,9 @@ If you'd like to get started with contributing to Koki Short, read our [Roadmap]
 ## Important Links
 
 - [Releases](https://github.com/koki/short/releases) 
-- [Docs]()
+- [Docs](https://docs.koki.io/short)
 - [Roadmap](https://github.com/koki/short/projects)
 - [Issues](https://github.com/koki/short/issues)
 
 ## LICENSE
-[Apache v2.0](LICENSE)
+[Apache v2.0](https://github.com/koki/short/blob/master/LICENSE)

docs/index.md

@@ -3,7 +3,7 @@
 Manageable Kubernetes manifests through composable, reusable syntax
 
 ## Motivation
-The description format for Kubernetes manifests, as it stands today, is verbose and unintuitive. Anecdotally, it has been 
+The description format for Kubernetes manifests, as it stands today, is verbose and unintuitive. Anecdotally, it has been:
 
  - Time consuming to write
  - Error-prone, hard to get right without referring to documentation
@@ -38,7 +38,7 @@ spec:
             - us-east2
 ```
 
-The Short format is designed to be user friendly, intuitive, reusable, and maintainable. The same pod denoted in Short syntax looks like
+The Short format is designed to be user friendly, intuitive, reusable, and maintainable. The same pod in Short syntax looks like
 
 ```yaml
 pod:
@@ -56,7 +56,7 @@ Our approach is to reframe Kubernetes manifests in an operator-friendly syntax w
 
 Koki Short can transform Kubernetes syntax into Short and Short syntax back into Kubernetes. No information is lost in either direction.
 
-For more information on Koki Short transformations, please refer to [Resources.](resources)
+For more information on Koki Short transformations, please refer to [Resources.](https://docs.koki.io/short/resources)
 
 ## Modular and Reusable
 
@@ -89,7 +89,7 @@ exports:
       affinity: ${affinity}  # re-use the affinity resource here
 ```
 
-For more information on Koki Modules, please refer to [Modules.](modules)
+For more information on Koki Modules, please refer to [Modules.](https://docs.koki.io/modules)
 
 ## Getting started
 
@@ -172,7 +172,7 @@ short man pod
 
 ```
 
-For more information, refer to our [getting started guide.](getting-started)
+For more information, refer to our [getting started guide.](https://docs.koki.io/user-guide#getting-started)
 
 ## Contribute
 Koki is completely open source community driven, including the roadmaps, planning, and implementation. We encourage everyone to help us make Kubernetes manifests more manageable. We welcome Issues, Pull Requests and participation in our [weekly meetings]().

docs/resources/deployment.md

@@ -50,33 +50,33 @@ The following sections contain detailed information about each field in Short sy
 |progress_deadline | `int32` | `progressDeadlineSeconds` | Maximum time for a deployment to make progress before it is considered unavailable|
 |selector | `map[string]string` or `string` | `selector` | An expression (string) or a set of key, value pairs (map) that is used to select a set of pods to manage using the deployment controller. See [Selector Overview](#selector-overview) |
 |pod_meta | `TemplateMetadata` | `template` | Metadata of the Pod that is selected by this Deployment. See [Template Metadata](#template-metadata)|
-|volumes | [`Volume`](./pod.md#volume-overview) | `spec.volumes` | Denotes the volumes that are a part of the Pod. See [Volume Overview](./pod.md#volume-overview) |
-| affinity | [`[]Affinity`](./pod.md#affinity-overview) | `spec.affinity` and `spec.NodeSelector` | The Pod's scheduling rules, expressed as (anti-)affinities for nodes or other Pods. See [Affinity Overview](./pod.md#affinity-overview) |
+|volumes | `Volume` | `spec.volumes` | Denotes the volumes that are a part of the Pod. See [Volume Overview](pod#volume-overview) |
+| affinity | `[]Affinity` | `spec.affinity` and `spec.NodeSelector` | The Pod's scheduling rules, expressed as (anti-)affinities for nodes or other Pods. See [Affinity Overview](pod#affinity-overview) |
 | node | `string` | `spec.nodeName` | Request that the Pod be scheduled on a specific node. | 
-| containers |[`Container`](../skel/container.short.skel.yaml) | `spec.containers` and `status`| Containers that run as a part of the Pod. See [Container Overview](./pod.md#container-overview) |
-| init_containers | [`Container`](../skel/container.short.skel.yaml) | `spec.initContainers` and `status` | Containers that run as a part of the initialization process of the Pod. See [Container Overview](./pod.md#container-overview) | 
-| dns_policy | [`DNSPolicy`](./pod.md#dns-policy-overview) | `spec.dnsPolicy` | The DNS Policy of the Pod. See [DNS Policy Overview](./pod.md#dns-policy-overview) |
-| host_aliases | `[]string` | `spec.aliases` | Set of additional records to be placed in `/etc/hosts` file inside the Pod. See [Host Aliases Overview](./pod.md#host-aliases-overview) |
-| host_mode | `[]string` | `spec.hostPID`, `spec.hostNetwork` and `spec.hostIPC`| The Pod's access to host resources. See [Host Mode Conversion](./pod.md#host-mode-conversion) |
+| containers |`Container` | `spec.containers` and `status`| Containers that run as a part of the Pod. See [Container Overview](pod#container-overview) |
+| init_containers | `Container` | `spec.initContainers` and `status` | Containers that run as a part of the initialization process of the Pod. See [Container Overview](pod#container-overview) | 
+| dns_policy | `DNSPolicy` | `spec.dnsPolicy` | The DNS Policy of the Pod. See [DNS Policy Overview](pod#dns-policy-overview) |
+| host_aliases | `[]string` | `spec.aliases` | Set of additional records to be placed in `/etc/hosts` file inside the Pod. See [Host Aliases Overview](pod#host-aliases-overview) |
+| host_mode | `[]string` | `spec.hostPID`, `spec.hostNetwork` and `spec.hostIPC`| The Pod's access to host resources. See [Host Mode Conversion](pod#host-mode-conversion) |
 | hostname | `string` | `spec.hostname` and `spec.subDomain` | The fully qualified domain name of the pod|
 | registry_secrets | `[]string` |`spec.ImagePullSecrets` | A list of k8s secret resource names that contain credentials to required to access private registries. |
-| restart_policy | [`RestartPolicy`](./pod.md#restart-policy) | `spec.restartPolicy` | Behavior of a Pod when it dies. Can be "always", "on-failure" or "never" |
+| restart_policy | `RestartPolicy` | `spec.restartPolicy` | Behavior of a Pod when it dies. Can be "always", "on-failure" or "never" |
 | scheduler_name | `string` | `spec.schedulerName` | The value from `spec.schedulerName` is stored here |
-| account | `string` | `spec.serviceAccountName` and `spec.automountServiceAccountToken` | The Pod's access to the K8s API. See [Account Conversion](./pod.md#account-conversion) | 
-| tolerations | [`[]Toleration`](../skel/toleration.short.skel.yaml) | `spec.tolerations` | Set of host taints this Pod tolerates. See [Toleration Conversion](./pod.md#toleration-conversion) |
-| termination_grace_period | `int64`  | `spec.terminationGracePeriodSeconds` | Number of seconds to wait before forcefully killing the Pod. |
-| active_deadline | `int64` | `spec.activeDeadlineSeconds`| Number of seconds the Pod is allowed to be active  |  
-| priority | `Priority` | `spec.priorityClassName` and `spec.priority` | Specifies the Pod's Priority. See [Priority](./pod.md#priority) |
-| condition | `[]Pod Condition` | `status.conditions` | The list of current and previous conditions of the Pod. See [Pod Condition](./pod.md#pod-condition) |
+| account | `string` | `spec.serviceAccountName` and `automountService` `AccountToken` | The Pod's access to the K8s API. See [Account Conversion](pod#account-conversion) | 
+| tolerations | `[]Toleration` | `spec.tolerations` | Set of host taints this Pod tolerates. See [Toleration Conversion](pod#toleration-conversion) |
+| termination_ grace_period | `int64`  | `spec.termination` `GracePeriodSeconds` | Number of seconds to wait before forcefully killing the Pod. |
+| active_deadline | `int64` | `spec.` `activeDeadlineSeconds`| Number of seconds the Pod is allowed to be active  |  
+| priority | `Priority` | `spec.priorityClassName` and `spec.priority` | Specifies the Pod's Priority. See [Priority](pod#priority) |
+| condition | `[]Pod Condition` | `status.conditions` | The list of current and previous conditions of the Pod. See [Pod Condition](pod#pod-condition) |
 | node_ip | `string` | `status.hostIP` | The IP address of the Pod's host | 
 | ip | `string` | `status.podIP` | The IP address of the Pod | 
 | start_time | `time` | `status.startTime` | When the Pod started running | 
 | msg | `string` | `status.message` | A human readable message explaining Pod's current condition |  
 | phase | `string` | `status.phase` | The current phase of the Pod |
 | reason | `string` | `status.reason` | Reason indicating the cause for the current state of the Pod |
 | qos | `string` | `status.qosClass` | The QOS class assigned to the Pod based on resource requirements |
-| fs_gid | `int64` | `spec.securityContext.fsGroup` | Special supplemental group that applies to all the Containers in the Pod |
-| gids | `[]int64` | `spec.securityContext.supplementalGroups` | A list of groups applied to the first process in each of the Containers in the Pod |
+| fs_gid | `int64` | `spec.securityContext.` `fsGroup` | Special supplemental group that applies to all the Containers in the Pod |
+| gids | `[]int64` | `spec.securityContext.` `supplementalGroups` | A list of groups applied to the first process in each of the Containers in the Pod |
 
 `max_unavailable` and `max_extra` are used to configure `RollingUpdate` deployment strategy. `max_unavailable` indicates the maximum number of pods that can be unavailable during update. The value can be number or a percentage value of the total number of replicas. Percentage values are represented using a `%` symbol at the end of the value.
 

docs/resources/index.md

@@ -87,4 +87,3 @@ The following types are currently supported
 | extensions/v1beta1 | Replica Set | [Replica Set](./replica-set.md) | [Replica Set Skeleton](./replica-set.md#skeleton) | [Replica Set Examples](./replica-set.md#examples) |
 | apps/v1beta2 | Replica Set | [Replica Set](./replica-set.md) | [Replica Set Skeleton](./replica-set.md#skeleton) | [Replica Set Examples](./replica-set.md#examples) |
 | core/v1 | Replication Controller | [Replication Controller](./replication-controller.md) | [Replication Controller Skeleton](./replication-controller.md#skeleton) | [Replication Controller Examples](./replication-controller.md#examples) |
-| core/v1 | PersistentVolume | [Volume](./volume.md) | [Volume Skeleton](./volume.md#skeleton) | [Volume Examples](./volume.md#examples) |