docs: Fix spelling and formatting

Correct typos and resolve formatting issues including incorrect heading
levels and missing TOC entries.

Fixes: #541.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

README.md

@@ -26,7 +26,7 @@ See the [OBS documentation](obs-packaging).
 
 Kata build artifacts are available within a container image, created by a
 [Dockerfile](kata-deploy/Dockerfile). Reference daemonsets are provided in
-[kata-deploy](kata-deploy), which make installation of Kata Containers in a
+[`kata-deploy`](kata-deploy), which make installation of Kata Containers in a
 running Kubernetes Cluster very straightforward.
 
 ## Build a snap package

ccloudvm/README.md

@@ -1,7 +1,7 @@
 # Test Kata using ccloudvm
 
 * [How to use Kata workloads for `ccloudvm`](#how-to-use-kata-workloads-for-ccloudvm)
-    * [Create Docker\* and Kata Containers virtualized enviroment](#create-docker-and-kata-containers-virtualized-enviroment)
+    * [Create Docker\* and Kata Containers virtualized environment](#create-docker-and-kata-containers-virtualized-environment)
 ---
 
 The [ccloudvm](https://github.com/intel/ccloudvm/) tool is a command
@@ -12,7 +12,7 @@ environments inside a virtual machine.
 
 - Follow the `ccloudvm` [install instructions](https://github.com/intel/ccloudvm/#introduction)
 
-### Create Docker\* and Kata Containers virtualized enviroment
+### Create Docker\* and Kata Containers virtualized environment
 
 Create a virtual machine with Docker and Kata containers.
 
@@ -21,6 +21,6 @@ $ ccloudvm create --name YOUR_VM_NAME $PWD/kata-docker-xenial.yaml
 $ ccloudvm connect YOUR_VM_NAME
 ```
 
-You are ready to use Kata with docker in a virtualized enviroment.
+You are ready to use Kata with docker in a virtualized environment.
 
 See `ccloudvm` [documentation](https://github.com/intel/ccloudvm/#configurable-cloud-vm-ccloudvm) for advanced usage.

cmd/kata-pkgsync/README.md

@@ -1,8 +1,12 @@
-### Kata OBS to Packagecloud sync tool
+# Kata OBS to Packagecloud sync tool
 
-`kata-pkgsync` is a tool to synchronize kata package from OBS to Packagecloud.
+* [How it works](#how-it-works)
+* [Detailed behaviour](#detailed-behaviour)
+* [Install and Usage](#install-and-usage)
 
-### How it works
+`kata-pkgsync` is a tool to synchronize Kata package from OBS to Packagecloud.
+
+## How it works
 
 `kata-pkgsync` autonomously discovers OBS packages, repositories, and architectures
 in a OBS project.
@@ -16,7 +20,7 @@ Based on this information, `kata-pkgsyncs` can download only the necessary
 files from OBS, upload them on Packagecloud, and delete orphans Packagecloud packages.
 
 
-### Detailed behaviour
+## Detailed behaviour
 
 This is the sequence of tasks executed:
 
@@ -34,7 +38,7 @@ of packages, to avoid re-downloading files if already done.
 6. Upload the identified files to Packagecloud.
 7. Optionally, delete orphans files from Packagecloud.
 
-### Install and Usage
+## Install and Usage
 
 Install with:
 ```

kata-deploy/README.md

@@ -1,21 +1,20 @@
-# kata-deploy
-
-- [kata-deploy](#kata-deploy)
-  * [Docker quick start](#docker-quick-start)
-    + [Install Kata and configure Docker](#install-kata-and-configure-docker)
-    + [Run a sample workload utilizing Kata containers](#run-a-sample-workload-utilizing-kata-containers)
-    + [Remove Kata](#remove-kata)
-  * [Kubernetes quick start](#kubernetes-quick-start)
-    + [Install Kata on a running Kubernetes cluster](#install-kata-on-a-running-kubernetes-cluster)
-    + [Run a sample workload](#run-a-sample-workload)
-    + [Remove Kata from the Kubernetes cluster](#remove-kata-from-the-kubernetes-cluster)
-  * [kata-deploy details](#kata-deploy-details)
-    + [Dockerfile](#dockerfile)
-    + [Daemonsets and RBAC](#daemonsets-and-rbac)
-      - [Kata deploy](#kata-deploy)
-      - [Kata cleanup](#kata-cleanup)
-
-[kata-deploy](.) provides a Dockerfile, which contains all of the binaries
+# `kata-deploy`
+
+* [Docker quick start](#docker-quick-start)
+    * [Install Kata and configure Docker](#install-kata-and-configure-docker)
+    * [Run a sample workload utilizing Kata containers](#run-a-sample-workload-utilizing-kata-containers)
+    * [Remove Kata](#remove-kata)
+* [Kubernetes quick start](#kubernetes-quick-start)
+    * [Install Kata on a running Kubernetes cluster](#install-kata-on-a-running-kubernetes-cluster)
+    * [Run a sample workload](#run-a-sample-workload)
+    * [Remove Kata from the Kubernetes cluster](#remove-kata-from-the-kubernetes-cluster)
+* [`kata-deploy` details](#kata-deploy-details)
+    * [Dockerfile](#dockerfile)
+    * [Daemonsets and RBAC](#daemonsets-and-rbac)
+        * [Kata deploy](#kata-deploy)
+        * [Kata cleanup](#kata-cleanup)
+
+[`kata-deploy`](.) provides a Dockerfile, which contains all of the binaries
 and artifacts required to run Kata Containers, as well as reference daemonsets, which can
 be utilized to install Kata Containers for both Docker and on a running Kubernetes cluster.
 
@@ -24,83 +23,83 @@ a node only if it uses either containerd or CRI-O CRI-shims.
 
 ## Docker quick start
 
-The kata-deploy container image makes use of a script, `kata-deploy-docker`, for installation of
+The `kata-deploy` container image makes use of a script, `kata-deploy-docker`, for installation of
 Kata artifacts and configuration of Docker to utilize the runtime. The following volumes are required to be mounted
 to aid in this:
-- /opt/kata: this is where all kata artifacts are installed on the system
-- /var/run/dbus, /run/systemd: this is require for reloading the the Docker service
-- /etc/docker: this is required for updating `daemon.json` in order to configure the kata runtimes in Docker
+- `/opt/kata`: this is where all Kata artifacts are installed on the system
+- `/var/run/dbus`, `/run/systemd`: this is require for reloading the the Docker service
+- `/etc/docker`: this is required for updating `daemon.json` in order to configure the Kata runtimes in Docker
 
 
 ### Install Kata and configure Docker
 
 To install:
 
 ```
-docker run -v /opt/kata:/opt/kata -v /var/run/dbus:/var/run/dbus -v /run/systemd:/run/systemd -v /etc/docker:/etc/docker -it katadocker/kata-deploy kata-deploy-docker install
+$ docker run -v /opt/kata:/opt/kata -v /var/run/dbus:/var/run/dbus -v /run/systemd:/run/systemd -v /etc/docker:/etc/docker -it katadocker/kata-deploy kata-deploy-docker install
 ```
 
-Once complete, `/etc/docker/daemon.json` is updated or created to include the Kata runtimes: kata-qemu and kata-fc, for utilizing
+Once complete, `/etc/docker/daemon.json` is updated or created to include the Kata runtimes: `kata-qemu` and `kata-fc`, for utilizing
 QEMU and Firecracker, respectively, for the VM isolation layer.
 
 ### Run a sample workload utilizing Kata containers
 
 Run a QEMU QEMU isolated Kata container:
 ```
-docker run --runtime=kata-qemu -itd alpine
+$ docker run --runtime=kata-qemu -itd alpine
 ```
 
 Run a Firecracker isolated Kata container:
 ```
-docker run --runtime=kata-fc -itd alpine
+$ docker run --runtime=kata-fc -itd alpine
 ```
 
 ### Remove Kata
 
 To uninstall:
 ```
-docker run -v /opt/kata:/opt/kata -v /var/run/dbus:/var/run/dbus -v /run/systemd:/run/systemd -v /etc/docker:/etc/docker -it katadocker/kata-deploy kata-deploy-docker remove
+$ docker run -v /opt/kata:/opt/kata -v /var/run/dbus:/var/run/dbus -v /run/systemd:/run/systemd -v /etc/docker:/etc/docker -it katadocker/kata-deploy kata-deploy-docker remove
 ```
 
-After completing, the original daemon.json, if it existed, is restored and all Kata artifacts from /opt/kata are removed.
+After completing, the original `daemon.json`, if it existed, is restored and all Kata artifacts from `/opt/kata` are removed.
 
 ## Kubernetes quick start
 
 ### Install Kata on a running Kubernetes cluster
 
 ```
-kubectl apply -f kata-rbac.yaml
-kubectl apply -f kata-deploy.yaml
+$ kubectl apply -f kata-rbac.yaml
+$ kubectl apply -f kata-deploy.yaml
 ```
 
 ### Run a sample workload
 
 
-Workloads which utilize Kata can node-select based on ```katacontainers.io/kata-runtime=true```, and are
-run through an applicable runtime if they are marked with the appropriate runtimeClass annotation.
+Workloads which utilize Kata can node-select based on `katacontainers.io/kata-runtime=true`, and are
+run through an applicable runtime if they are marked with the appropriate `runtimeClass` annotation.
 
 
 In order to use a workload Kata with QEMU, first add a `RuntimeClass` as:
 - For k8s 1.14:
   ```
-  kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.14/kata-qemu-runtimeClass.yaml
+  $ kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.14/kata-qemu-runtimeClass.yaml
   ```
 
 - For k8s 1.13:
   ```
-  kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.13/kata-qemu-runtimeClass.yaml
+  $ kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.13/kata-qemu-runtimeClass.yaml
   ```
 
 
 In order to use a workload Kata with Firecracker, first add a `RuntimeClass` as:
 - For k8s 1.14:
   ```
-  kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.14/kata-fc-runtimeClass.yaml
+  $ kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.14/kata-fc-runtimeClass.yaml
   ```
 
 - For k8s 1.13:
   ```
-  kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.13/kata-fc-runtimeClass.yaml
+  $ kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/k8s-1.13/kata-fc-runtimeClass.yaml
   ```
 
 The following YAML snippet shows how to specify a workload should use Kata with QEMU:
@@ -119,34 +118,34 @@ spec:
       runtimeClassName: kata-fc
 ```
 
-To run an example with kata-qemu:
+To run an example with `kata-qemu`:
 
 ```
-kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-qemu.yaml
+$ kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-qemu.yaml
 ```
 
-To run an example with kata-fc:
+To run an example with `kata-fc`:
 
 ```
-kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-fc.yaml
+$ kubectl apply -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-fc.yaml
 ```
 
 The following removes the test pods:
 ```
-kubectl delete -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-qemu.yaml
-kubectl delete -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-fc.yaml
+$ kubectl delete -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-qemu.yaml
+$ kubectl delete -f https://raw.githubusercontent.com/kata-containers/packaging/master/kata-deploy/examples/test-deploy-kata-fc.yaml
 ```
 
 ### Remove Kata from the Kubernetes cluster
 
 ```
-kubectl delete -f kata-deploy.yaml
-kubectl apply -f kata-cleanup.yaml
-kubectl delete -f kata-cleanup.yaml
-kubectl delete -f kata-rbac.yaml
+$ kubectl delete -f kata-deploy.yaml
+$ kubectl apply -f kata-cleanup.yaml
+$ kubectl delete -f kata-cleanup.yaml
+$ kubectl delete -f kata-rbac.yaml
 ```
 
-## kata-deploy details
+## `kata-deploy` details
 
 ### Dockerfile
 
@@ -155,34 +154,34 @@ This image contains all the necessary artifacts for running Kata Containers, all
 from the [Kata Containers release page](https://github.com/kata-containers/runtime/releases).
 
 Host artifacts:
-* kata-runtime
-* kata-fc
-* kata-qemu
-* kata-proxy
-* kata-shim
-* firecracker
-* qemu-system-x86_64 and supporting binaries
+* `kata-runtime`
+* `kata-fc`
+* `kata-qemu`
+* `kata-proxy`
+* `kata-shim`
+* `firecracker`
+* `qemu-system-x86_64` and supporting binaries
 
 Virtual Machine artifacts:
-* kata-containers.img: pulled from Kata github releases page
-* vmliuz.container: pulled from Kata github releases page
+* `kata-containers.img`: pulled from Kata github releases page
+* `vmliuz.container`: pulled from Kata github releases page
 
 ### Daemonsets and RBAC
 
-Two daemonsets are introduced for kata-deploy, as well as an RBAC to facilitate
+Two daemonsets are introduced for `kata-deploy`, as well as an RBAC to facilitate
 applying labels to the nodes.
 
 #### Kata deploy
 
-This daemonset installs the necessary kata binaries, configuration files, and virtual machine artifacts on
+This daemonset installs the necessary Kata binaries, configuration files, and virtual machine artifacts on
 the node. Once installed, the daemonset adds a node label `katacontainers.io/kata-runtime=true` and reconfigures
-either CRI-O or containerd to register two runtimeClasses: `kata-qemu` (for QEMU isolation) and `kata-fc` (for Firecracker isolation).
+either CRI-O or containerd to register two `runtimeClasses`: `kata-qemu` (for QEMU isolation) and `kata-fc` (for Firecracker isolation).
 As a final step the daemonset restarts either CRI-O or containerd. Upon deletion, the daemonset removes the
-Kata binaries and VM artifacts and updates the node label to `katacontainers.io/kata-runtime=cleanup.`
+Kata binaries and VM artifacts and updates the node label to `katacontainers.io/kata-runtime=cleanup`.
 
 #### Kata cleanup
 
-This daemonset runs of the node has the label `katacontainers.io/kata-runtime=cleanup.` These daemonsets removes
-the `katacontainers.io/kata-runtime` label as well as restarts either CRI-O or containerd systemctl
-daemon. You cannot execute these resets during the preStopHook of the Kata installer daemonset,
+This daemonset runs of the node has the label `katacontainers.io/kata-runtime=cleanup`. These daemonsets removes
+the `katacontainers.io/kata-runtime` label as well as restarts either CRI-O or `containerd` `systemctl`
+daemon. You cannot execute these resets during the `preStopHook` of the Kata installer daemonset,
 which necessitated this final cleanup daemonset.

kernel/README.md

@@ -1,16 +1,13 @@
-* [Build Kata Containers Kernel](#build-kata-containers-kernel)
-    * [Requirements](#requirements)
-    * [Setup kernel source code](#setup-kernel-source-code)
+# Build Kata Containers Kernel
+
+* [Requirements](#requirements)
+* [Setup kernel source code](#setup-kernel-source-code)
 * [Build the kernel](#build-the-kernel)
-    * [Install the Kernel in the default path for Kata](#install-the-kernel-in-the-default-path-for-kata)
-    * [Submit Kernel Changes](#submit-kernel-changes)
-    * [How is it tested](#how-is-it-tested)
+* [Install the Kernel in the default path for Kata](#install-the-kernel-in-the-default-path-for-kata)
+* [Submit Kernel Changes](#submit-kernel-changes)
+* [How is it tested](#how-is-it-tested)
 * [Contribute](#contribute)
 
----
-
-# Build Kata Containers Kernel
-
 This document explains the steps to build a kernel recommended for use with
 Kata Containers. To do this use `build-kernel.sh`, this script
 automates the process to build a kernel for Kata Containers.
@@ -35,15 +32,14 @@ The script also adds a kernel config file from
 `${GOPATH}/src/github.com/kata-containers/packaging/kernel/configs/` to `.config`
 in the kernel source code. You can modify it as needed.
 
-# Build the kernel
+## Build the kernel
 
 After the kernel source code is ready, it is possible to build the kernel.
 
 ```bash
 $ ./build-kernel.sh build
 ```
 
-
 ## Install the Kernel in the default path for Kata
 
 Kata Containers uses some default path to search a kernel to boot. To install
@@ -89,7 +85,7 @@ $ latest_kernel_version=${kernel_version_in_versions_file}-${kata_config_version
 The resulting version is 4.10.1-25, this helps identify whether or not the kernel
 configs are up-to-date on a CI version.
 
-# Contribute
+## Contribute
 
 In order to do Kata Kernel changes. There are places to contribute:
 
@@ -123,7 +119,7 @@ In order to do Kata Kernel changes. There are places to contribute:
 Note: The kernel version and configuration file live in different locations,
 which could result in a circular dependency on your (runtime or packaging) PR.
 In this case, the PR you submit needs to be tested together with a patch from
-another kata-containers repository. To do this you have to specify which
+another Kata Containers repository. To do this you have to specify which
 repository and which pull request [it depends on][depends-on-docs].
 
 [runtime-versions-file]: https://github.com/kata-containers/runtime/blob/master/versions.yaml