Merge pull request #2865 from chrislovecnm/yaml-docs-fixes

Doc fixes

docs/README.md

@@ -28,29 +28,30 @@
 * [kubectl](kubectl.md)
     * how to point kubectl to your `kops` cluster
 
+## Advanced / Detailed List of Configurations
+
+### API / Configuration References
+* [Godocs for Cluster - `ClusterSepc`](https://godoc.org/k8s.io/kops/pkg/apis/kops#ClusterSpec).
+* [Godocs for Instance Group - `InstanceGroupSpec`](https://godoc.org/k8s.io/kops/pkg/apis/kops#InstanceGroupSpec).
+
+### API Usage Guides
+* [`kops` cluster API definitions](cluster_spec.md)
+    * overview of some of the API value to customize a `kops` cluster
+* [`kops` instance groups API](instance_groups.md)
+    * overview of some of the API value to customize a `kops` groups of k8s nodes
+* [Using Manifests and Customizing via the API](manifests_and_customizing_via_api.md)
 
 ## Operations
-
-* API / Manifest Custom Values
-    * [godocs Cluster specific documentation - `spec`](https://godoc.org/k8s.io/kops/pkg/apis/kops#ClusterSpec).
-    * [godocs Instance Group specific documentation - `spec`] (https://godoc.org/k8s.io/kops/pkg/apis/kops#InstanceGroupSpec).
 * [Cluster addon manager](addon_manager.md)
 * [Cluster addons](addons.md)
 * [Cluster configuration management](changing_configuration.md)
-* [`kops` cluster API definitions](cluster_spec.md)
-    * overview of some of the API value to customize a `kops` cluster
 * [Cluster upgrades and migrations](cluster_upgrades_and_migrations.md)
 * [`etcd` volume encryption setup](etcd_volume_encryption.md)
 * [`etcd` backup setup](etcd_backup.md)
 * [GPU setup](gpu.md)
 * [High Availability](high_availability.md)
-* [`kops` instance groups API](instance_groups.md)
-    * overview of some of the API value to customize a `kops` groups of ks8 nodes
 * [InstanceGroup images](images.md)
     * how to use other image for cluster nodes, and information on available/tested images
-* [Using Manifests and Customization via the API](manifests_and_customizing_via_api.md)
-    * how to use YAML to manage clusters.
-    * how to customize cluster via the `kops` API.
 * [`k8s` upgrading](upgrade.md)
 * [`kops` updating](update_kops.md)
 * [`kube-up` to `kops` upgrade](upgrade_from_kubeup.md)

docs/manifests_and_customizing_via_api.md

@@ -15,11 +15,11 @@ The following is a list of the benefits of using a file to manage instances.
 - Ability to check-in files to source control that represents an installation.
 - Run commands such as `kops delete -f mycuster.yaml`.
 
-# Exporting a Cluster
+## Exporting a Cluster
 
 At this time you must run `kops create cluster` and then export the YAML from the state store.   We plan in the future to have the capability to generate kops YAML via the command line.  The following is an example of creating a cluster and exporting the YAML.
 
-```
+```shell
 export NAME=k8s.example.com
 export KOPS_STATE_STORE=s3://example-state-store
  kops create cluster $NAME \
@@ -37,7 +37,7 @@ export KOPS_STATE_STORE=s3://example-state-store
 
 The next step is to export the configuration to a YAML document.  `kops` has a command that allows the export in a single YAML document, but since JSON files need to separate documents, we only export YAML with a single command.  You can export JSON with multiple commands.
 
-```
+```shell
 kops get $NAME -o yaml > $NAME.yaml
 ```
 
@@ -45,7 +45,7 @@ The above command exports a YAML document which contains the definition of the c
 
 The following is the contents of the exported YAML file.
 
-```YAML
+```yaml
 apiVersion: kops/v1alpha2
 kind: Cluster
 metadata:
@@ -222,19 +222,17 @@ spec:
 
 Next, delete the cluster from the state store.
 
-```
+```console
 kops delete -f $NAME.yaml
 # validate that you want to remove the cluster
 kops delete -f $NAME.yaml --yes
 ```
 
-## YAML examples
-
-FIXME: rename this section.
+## YAML Examples
 
 With the above YAML file, a user can add configurations that are not available via the command line.  For instance, you can add a `MaxPrice` value to a new instance group and use spot instances.  Also add node and cloud labels for the new instance group.
 
-```
+```yaml
 apiVersion: kops/v1alpha2
 kind: InstanceGroup
 metadata:
@@ -262,7 +260,7 @@ This configuration will create an autoscale group that will include 42 m4.10xlar
 
 To create the cluster execute:
 
-```
+```shell
 kops create -f $NAME.yaml
 kops create secret --name $NAME sshpublickey admin -i ~/.ssh/id_rsa.pub
 kops update cluster $NAME --yes
@@ -273,7 +271,7 @@ Please refer to the rolling-update [documentation](cli/kops_rolling-update_clust
 
 Update the cluster spec YAML file, and to update the cluster run:
 
-```
+```shell
 kops replace -f $NAME.yaml
 kops update cluster $NAME --yes
 kops rolling-update cluster $NAME --yes
@@ -287,7 +285,7 @@ Please refer to the rolling-update [documentation](cli/kops_rolling-update_clust
 
 ### Cluster Spec
 
-```YAML
+```yaml
 apiVersion: kops/v1alpha2
 kind: Cluster
 metadata:
@@ -312,7 +310,7 @@ More information about some of the elements in the `ClusterSpec` is available in
 
 To access the full configuration that a `kops` installation is running execute:
 
-```
+```bash
 kops get cluster $NAME --full -o yaml
 ```
 
@@ -320,7 +318,7 @@ This command prints the entire YAML configuration.  But _do not_ use the full do
 
 ### Instance Groups
 
-```YAML
+```yaml
 apiVersion: kops/v1alpha2
 kind: InstanceGroup
 metadata: