Merge pull request #516 from jodh-intel/improve-docs

Improve docs

Jenkinsfiles/README.md

@@ -0,0 +1,8 @@
+# Jenkins
+
+Kata Containers uses [Jenkins](https://jenkins.io/)
+for [its main CI](http://jenkins.katacontainers.io/).
+
+This directory contains support files for the Jenkins
+[pipeline](https://jenkins.io/doc/book/pipeline/)
+[plugin](https://wiki.jenkins.io/display/JENKINS/Pipeline+Plugin).

README.md

@@ -1,11 +1,65 @@
 # Kata Containers packaging
 
-Kata Containers currently supports packages for many distributions. Tooling to aid in creating these
-packages are contained within this repository.
+* [Introduction](#introduction)
+* [Build using OBS](#build-using-obs)
+* [Build in a container](#build-in-a-container)
+* [Build a snap package](#build-a-snap-package)
+* [Build static binaries](#build-static-binaries)
+* [Build Kata Containers Kernel](#build-kata-containers-kernel)
+* [Build QEMU](#build-qemu)
+* [Test Kata using ccloudvm](#test-kata-using-ccloudvm)
+* [Create a Kata Containers release](#create-a-kata-containers-release)
+* [Jenkins files](#jenkins-files)
+* [Packaging scripts](#packaging-scripts)
+* [Credits](#credits)
 
-In addition, 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 running Kubernetes Cluster very straightforward.
+## Introduction
+
+Kata Containers currently supports packages for many distributions. Tooling to
+aid in creating these packages are contained within this repository.
+
+## Build using OBS
+
+See the [OBS documentation](obs-packaging).
+
+## Build in a container
+
+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
+running Kubernetes Cluster very straightforward.
+
+## Build a snap package
+
+See [the snap documentation](snap).
+
+## Build static binaries
+
+See [the static build documentation](static-build).
+
+## Build Kata Containers Kernel
+
+See [the kernel documentation](kernel).
+
+## Build QEMU
+
+See [the QEMU documentation](qemu).
+
+## Test Kata using ccloudvm
+
+See [the ccloudvm documentation](ccloudvm).
+
+## Create a Kata Containers release
+
+See [the release documentation](release).
+
+## Jenkins files
+
+See [the Jenkins documentation](Jenkinsfiles).
+
+## Packaging scripts
+
+See the [scripts documentation](scripts).
 
 ## Credits
 

kernel/README.md

@@ -60,6 +60,8 @@ Kata Containers packaging repository holds the kernel configs and patches. The
 config and patches can work for many versions, but we only test the
 kernel version defined in the [runtime versions file][runtime-versions-file].
 
+For further details, see [the kernel configuration documentation](configs).
+
 ## How is it tested
 
 The Kata Containers CI scripts install the kernel from [CI cache

obs-packaging/README.md

@@ -0,0 +1,11 @@
+# Building under OBS
+
+SUSE's [Open Build Service (OBS)](https://openbuildservice.org) is used to
+build [the official Kata Containers packages](https://build.opensuse.org/project/subprojects/home:katacontainers).
+
+This directory contains tooling and packaging metadata to build all Kata
+components with OBS.
+
+See
+[the Kata installation documentation](https://github.com/kata-containers/documentation/blob/master/install/README.md)
+for instructions on how to install the official packages.

qemu/README.md

@@ -0,0 +1,3 @@
+# QEMU patches
+
+This directory contains patches used to build QEMU.

release/README.md

@@ -1,8 +1,20 @@
-# Release tools #
+# Release tools
+
+* [Introduction](#introduction)
+* [Create a Kata Containers release](#create-a-kata-containers-release)
+* [`update-repository-version.sh`](#update-repository-versionsh)
+* [Update Kata projects to a new version](#update-kata-projects-to-a-new-version)
+* [`tag_repos.sh`](#tag_repossh)
+
+## Introduction
 
 This directory contains tools for Kata Containers releases.
 
-## update-repository-version.sh ##
+## Create a Kata Containers release
+
+See [the release documentation](release.md).
+
+## `update-repository-version.sh`
 
 This script creates a GitHub pull request (a.k.a PR) to change the version in
 all the Kata repositories.
@@ -13,7 +25,8 @@ For more information on using the script, run the following:
 $ ./update-repository-version.sh -h
 ```
 
-### Update Kata projects to a new version ###
+## Update Kata projects to a new version
+
 Kata Containers is divided into multiple projects. With each release, all
 project versions are updated to keep the version consistent.
 
@@ -23,12 +36,12 @@ To update all versions for all projects, use the following:
 $ make bump-kata-version NEW_VERSION=<new-version>
 ```
 
-The makefile target bump-kata-version creates a GitHub pull request in the Kata
-repositories. These pull requests are tested by the Kata CI to ensure the
+The makefile target `bump-kata-version` creates a GitHub pull request in the
+Kata repositories. These pull requests are tested by the Kata CI to ensure the
 entire project is working prior to the release. Next, the PR is approved and
 merged by Kata Containers members.
 
-## tag_repos.sh ##
+## `tag_repos.sh`
 
 After all the Kata repositories are updated with a new version, they need to be
 tagged.

static-build/README.md

@@ -0,0 +1,3 @@
+# Static build
+
+This directory contains files to build static versions of Kata Containers.