docs: Remove table of contents

Removed all TOCs now that GitHub auto-generates them. Also updated the documentation requirements doc removing the requirement to add a TOC. Fixes: kata-containers#2022. Signed-off-by: James O. D. Hunt <[email protected]>
dong-df · Jul 30, 2021 · 4f0726b · 4f0726b
1 parent f186c5e
commit 4f0726b
Show file tree

Hide file tree

Showing 66 changed files with 21 additions and 676 deletions.
diff --git a/README.md b/README.md
@@ -2,23  2,6 @@
 
 # Kata Containers
 
-* [Kata Containers](#kata-containers)
-    * [Introduction](#introduction)
-    * [Getting started](#getting-started)
-    * [Documentation](#documentation)
-    * [Community](#community)
-    * [Getting help](#getting-help)
-        * [Raising issues](#raising-issues)
-            * [Kata Containers 1.x versions](#kata-containers-1x-versions)
-    * [Developers](#developers)
-        * [Components](#components)
-            * [Kata Containers 1.x components](#kata-containers-1x-components)
-        * [Common repositories](#common-repositories)
-        * [Packaging and releases](#packaging-and-releases)
-    * [Glossary of Terms](#glossary-of-terms)
-
----
-
 Welcome to Kata Containers!
 
 This repository is the home of the Kata Containers code for the 2.0 and newer

diff --git a/docs/Developer-Guide.md b/docs/Developer-Guide.md
@@ -1,56  1,3 @@
-- [Warning](#warning)
-- [Assumptions](#assumptions)
-- [Initial setup](#initial-setup)
-- [Requirements to build individual components](#requirements-to-build-individual-components)
-- [Build and install the Kata Containers runtime](#build-and-install-the-kata-containers-runtime)
-- [Check hardware requirements](#check-hardware-requirements)
-  - [Configure to use initrd or rootfs image](#configure-to-use-initrd-or-rootfs-image)
-  - [Enable full debug](#enable-full-debug)
-    - [debug logs and shimv2](#debug-logs-and-shimv2)
-      - [Enabling full `containerd` debug](#enabling-full-containerd-debug)
-      - [Enabling just `containerd shim` debug](#enabling-just-containerd-shim-debug)
-      - [Enabling `CRI-O` and `shimv2` debug](#enabling-cri-o-and-shimv2-debug)
-    - [journald rate limiting](#journald-rate-limiting)
-      - [`systemd-journald` suppressing messages](#systemd-journald-suppressing-messages)
-      - [Disabling `systemd-journald` rate limiting](#disabling-systemd-journald-rate-limiting)
-- [Create and install rootfs and initrd image](#create-and-install-rootfs-and-initrd-image)
-  - [Build a custom Kata agent - OPTIONAL](#build-a-custom-kata-agent---optional)
-  - [Get the osbuilder](#get-the-osbuilder)
-  - [Create a rootfs image](#create-a-rootfs-image)
-    - [Create a local rootfs](#create-a-local-rootfs)
-    - [Add a custom agent to the image - OPTIONAL](#add-a-custom-agent-to-the-image---optional)
-    - [Build a rootfs image](#build-a-rootfs-image)
-    - [Install the rootfs image](#install-the-rootfs-image)
-  - [Create an initrd image - OPTIONAL](#create-an-initrd-image---optional)
-    - [Create a local rootfs for initrd image](#create-a-local-rootfs-for-initrd-image)
-    - [Build an initrd image](#build-an-initrd-image)
-    - [Install the initrd image](#install-the-initrd-image)
-- [Install guest kernel images](#install-guest-kernel-images)
-- [Install a hypervisor](#install-a-hypervisor)
-  - [Build a custom QEMU](#build-a-custom-qemu)
-    - [Build a custom QEMU for aarch64/arm64 - REQUIRED](#build-a-custom-qemu-for-aarch64arm64---required)
-- [Run Kata Containers with Containerd](#run-kata-containers-with-containerd)
-- [Run Kata Containers with Kubernetes](#run-kata-containers-with-kubernetes)
-- [Troubleshoot Kata Containers](#troubleshoot-kata-containers)
-- [Appendices](#appendices)
-  - [Checking Docker default runtime](#checking-docker-default-runtime)
-  - [Set up a debug console](#set-up-a-debug-console)
-    - [Simple debug console setup](#simple-debug-console-setup)
-      - [Enable agent debug console](#enable-agent-debug-console)
-      - [Start `kata-monitor` - ONLY NEEDED FOR 2.0.x](#start-kata-monitor---only-needed-for-20x)
-      - [Connect to debug console](#connect-to-debug-console)
-    - [Traditional debug console setup](#traditional-debug-console-setup)
-      - [Create a custom image containing a shell](#create-a-custom-image-containing-a-shell)
-      - [Build the debug image](#build-the-debug-image)
-      - [Configure runtime for custom debug image](#configure-runtime-for-custom-debug-image)
-      - [Create a container](#create-a-container)
-      - [Connect to the virtual machine using the debug console](#connect-to-the-virtual-machine-using-the-debug-console)
-        - [Enabling debug console for QEMU](#enabling-debug-console-for-qemu)
-        - [Enabling debug console for cloud-hypervisor / firecracker](#enabling-debug-console-for-cloud-hypervisor--firecracker)
-        - [Connecting to the debug console](#connecting-to-the-debug-console)
-  - [Obtain details of the image](#obtain-details-of-the-image)
-  - [Capturing kernel boot logs](#capturing-kernel-boot-logs)
-
 # Warning
 
 This document is written **specifically for developers**: it is not intended for end users.

diff --git a/docs/Documentation-Requirements.md b/docs/Documentation-Requirements.md
@@ -1,16  1,3 @@
-* [Introduction](#introduction)
-* [General requirements](#general-requirements)
-* [Linking advice](#linking-advice)
-* [Notes](#notes)
-* [Warnings and other admonitions](#warnings-and-other-admonitions)
-* [Files and command names](#files-and-command-names)
-* [Code blocks](#code-blocks)
-* [Images](#images)
-* [Spelling](#spelling)
-* [Names](#names)
-* [Version numbers](#version-numbers)
-* [The apostrophe](#the-apostrophe)
-
 # Introduction
 
 This document outlines the requirements for all documentation in the [Kata
@@ -23,10  10,6 @@ All documents must:
 - Be written in simple English.
 - Be written in [GitHub Flavored Markdown](https://github.github.com/gfm) format.
 - Have a `.md` file extension.
-- Include a TOC (table of contents) at the top of the document with links to
-  all heading sections. We recommend using the
-  [`kata-check-markdown`](https://github.com/kata-containers/tests/tree/main/cmd/check-markdown)
-  tool to generate the TOC.
 - Be linked to from another document in the same repository.
 
   Although GitHub allows navigation of the entire repository, it should be
@@ -43,6  26,10 @@ All documents must:
   which can then execute the commands specified to ensure the instructions are
   correct. This avoids documents becoming out of date over time.
 
 > **Note:**
 >
 > Do not add a table of contents (TOC) since GitHub will auto-generate one.
 
 # Linking advice
 
 Linking between documents is strongly encouraged to help users and developers

diff --git a/docs/Licensing-strategy.md b/docs/Licensing-strategy.md
@@ -1,9  1,5 @@
 # Licensing strategy
 
-* [Project License](#project-license)
-* [License file](#license-file)
-* [License for individual files](#license-for-individual-files)      
-
 ## Project License
 
 The license for the [Kata Containers](https://github.com/kata-containers)

diff --git a/docs/Limitations.md b/docs/Limitations.md
@@ -1,35  1,3 @@
-* [Overview](#overview)
-* [Definition of a limitation](#definition-of-a-limitation)
-* [Scope](#scope)
-* [Contributing](#contributing)
-* [Pending items](#pending-items)
-    * [Runtime commands](#runtime-commands)
-        * [checkpoint and restore](#checkpoint-and-restore)
-        * [events command](#events-command)
-        * [update command](#update-command)
-    * [Networking](#networking)
-        * [Docker swarm and compose support](#docker-swarm-and-compose-support)
-    * [Resource management](#resource-management)
-        * [docker run and shared memory](#docker-run-and-shared-memory)
-        * [docker run and sysctl](#docker-run-and-sysctl)
-    * [Docker daemon features](#docker-daemon-features)
-        * [SELinux support](#selinux-support)
-* [Architectural limitations](#architectural-limitations)
-    * [Networking limitations](#networking-limitations)
-        * [Support for joining an existing VM network](#support-for-joining-an-existing-vm-network)
-        * [docker --net=host](#docker---nethost)
-        * [docker run --link](#docker-run---link)
-    * [Storage limitations](#storage-limitations)
-        * [Kubernetes `volumeMounts.subPaths`](#kubernetes-volumemountssubpaths)
-    * [Host resource sharing](#host-resource-sharing)
-        * [docker run --privileged](#docker-run---privileged)
-* [Miscellaneous](#miscellaneous)
-    * [Docker --security-opt option partially supported](#docker---security-opt-option-partially-supported)
-* [Appendices](#appendices)
-    * [The constraints challenge](#the-constraints-challenge)
-
-***
-
 # Overview
 
 A [Kata Container](https://github.com/kata-containers) utilizes a Virtual Machine (VM) to enhance security and

diff --git a/docs/README.md b/docs/README.md
@@ -1,16  1,5 @@
 # Documentation
 
-* [Getting Started](#getting-started)
-* [More User Guides](#more-user-guides)
-* [Kata Use-Cases](#kata-use-cases)
-* [Developer Guide](#developer-guide)
-    * [Design and Implementations](#design-and-implementations)
-    * [How to Contribute](#how-to-contribute)
-    * [Code Licensing](#code-licensing)
-    * [The Release Process](#the-release-process)
-* [Help Improving the Documents](#help-improving-the-documents)
-* [Website Changes](#website-changes)
-
 The [Kata Containers](https://github.com/kata-containers)
 documentation repository hosts overall system documentation, with information
 common to multiple components.

diff --git a/docs/Release-Process.md b/docs/Release-Process.md
@@ -1,20  1,6 @@
-
 # How to do a Kata Containers Release
   This document lists the tasks required to create a Kata Release.
 
-<!-- TOC START min:1 max:3 link:true asterisk:false update:true -->
-- [How to do a Kata Containers Release](#how-to-do-a-kata-containers-release)
-  - [Requirements](#requirements)
-  - [Release Process](#release-process)
-    - [Bump all Kata repositories](#bump-all-kata-repositories)
-    - [Merge all bump version Pull requests](#merge-all-bump-version-pull-requests)
-    - [Tag all Kata repositories](#tag-all-kata-repositories)
-    - [Check Git-hub Actions](#check-git-hub-actions)
-    - [Create release notes](#create-release-notes)
-    - [Announce the release](#announce-the-release)
-<!-- TOC END -->
-
-
 ## Requirements
 
 - [hub](https://github.com/github/hub)

diff --git a/docs/Upgrading.md b/docs/Upgrading.md
@@ -1,16  1,3 @@
-* [Introduction](#introduction)
-* [Maintenance warning](#maintenance-warning)
-* [Determine current version](#determine-current-version)
-* [Determine latest version](#determine-latest-version)
-* [Configuration changes](#configuration-changes)
-* [Upgrade Kata Containers](#upgrade-kata-containers)
-    * [Upgrade native distribution packaged version](#upgrade-native-distribution-packaged-version)
-    * [Static installation](#static-installation)
-        * [Determine if you are using a static installation](#determine-if-you-are-using-a-static-installation)
-        * [Remove a static installation](#remove-a-static-installation)
-        * [Upgrade a static installation](#upgrade-a-static-installation)
-* [Custom assets](#custom-assets)
-
 # Introduction
 
 This document outlines the options for upgrading from a

diff --git a/docs/design/VSocks.md b/docs/design/VSocks.md
@@ -1,12  1,5 @@
 # Kata Containers and VSOCKs
 
-- [Introduction](#introduction)
-    - [VSOCK communication diagram](#vsock-communication-diagram)
-- [System requirements](#system-requirements)
-- [Advantages of using VSOCKs](#advantages-of-using-vsocks)
-    - [High density](#high-density)
-    - [Reliability](#reliability)
-
 ## Introduction
 
 There are two different ways processes in the virtual machine can communicate

diff --git a/docs/design/architecture.md b/docs/design/architecture.md
@@ -1,26  1,5 @@
 # Kata Containers Architecture
 
-
-- [Kata Containers Architecture](#kata-containers-architecture)
-  - [Overview](#overview)
-  - [Virtualization](#virtualization)
-  - [Guest assets](#guest-assets)
-    - [Guest kernel](#guest-kernel)
-    - [Guest image](#guest-image)
-      - [Root filesystem image](#root-filesystem-image)
-      - [Initrd image](#initrd-image)
-  - [Agent](#agent)
-  - [Runtime](#runtime)
-    - [Configuration](#configuration)
-  - [Networking](#networking)
-    - [Network Hotplug](#network-hotplug)
-  - [Storage](#storage)
-  - [Kubernetes support](#kubernetes-support)
-      - [OCI annotations](#oci-annotations)
-      - [Mixing VM based and namespace based runtimes](#mixing-vm-based-and-namespace-based-runtimes)
-- [Appendices](#appendices)
-  - [DAX](#dax)
-
 ## Overview
 
 This is an architectural overview of Kata Containers, based on the 2.0 release.

diff --git a/docs/design/end-to-end-flow.md b/docs/design/end-to-end-flow.md
@@ -1,4  1,3 @@
 # Kata Containers E2E Flow
 
-
 ![Kata containers e2e flow](arch-images/katacontainers-e2e-with-bg.jpg)
diff --git a/docs/design/host-cgroups.md b/docs/design/host-cgroups.md
@@ -1,18  1,3 @@
-- [Host cgroup management](#host-cgroup-management)
-  - [Introduction](#introduction)
-  - [`SandboxCgroupOnly` enabled](#sandboxcgrouponly-enabled)
-    - [What does Kata do in this configuration?](#what-does-kata-do-in-this-configuration)
-    - [Why create a Kata-cgroup under the parent cgroup?](#why-create-a-kata-cgroup-under-the-parent-cgroup)
-    - [Improvements](#improvements)
-  - [`SandboxCgroupOnly` disabled (default, legacy)](#sandboxcgrouponly-disabled-default-legacy)
-    - [What does this method do?](#what-does-this-method-do)
-      - [Impact](#impact)
-- [Supported cgroups](#supported-cgroups)
-  - [Cgroups V1](#cgroups-v1)
-  - [Cgroups V2](#cgroups-v2)
-    - [Distro Support](#distro-support)
-- [Summary](#summary)
-
 # Host cgroup management
 
 ## Introduction

diff --git a/docs/design/kata-2-0-metrics.md b/docs/design/kata-2-0-metrics.md
@@ -1,20  1,5 @@
 # Kata 2.0 Metrics Design
 
-* [Limitations of Kata 1.x and the target of Kata 2.0](#limitations-of-kata-1x-and-the-target-of-kata-20)
-* [Metrics architecture](#metrics-architecture)
-  * [Kata monitor](#kata-monitor)
-  * [Kata runtime](#kata-runtime)
-  * [Kata agent](#kata-agent)
-  * [Performance and overhead](#performance-and-overhead)
-* [Metrics list](#metrics-list)
-  * [Metric types](#metric-types)
-  * [Kata agent metrics](#kata-agent-metrics)
-  * [Firecracker metrics](#firecracker-metrics)
-  * [Kata guest OS metrics](#kata-guest-os-metrics)
-  * [Hypervisor metrics](#hypervisor-metrics)
-  * [Kata monitor metrics](#kata-monitor-metrics)
-  * [Kata containerd shim v2 metrics](#kata-containerd-shim-v2-metrics)
-
 Kata implement CRI's API and support [`ContainerStats`](https://github.com/kubernetes/kubernetes/blob/release-1.18/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto#L101) and [`ListContainerStats`](https://github.com/kubernetes/kubernetes/blob/release-1.18/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto#L103) interfaces to expose containers metrics. User can use these interface to get basic metrics about container.
 
 But unlike `runc`, Kata is a VM-based runtime and has a different architecture.

diff --git a/docs/design/kata-api-design.md b/docs/design/kata-api-design.md
@@ -1,4  1,5 @@
 # Kata API Design
 
 To fulfill the [Kata design requirements](kata-design-requirements.md), and based on the discussion on [Virtcontainers API extensions](https://docs.google.com/presentation/d/1dbGrD1h9cpuqAPooiEgtiwWDGCYhVPdatq7owsKHDEQ), the Kata runtime library features the following APIs:
 -  Sandbox based top API
 -  Storage and network hotplug API

diff --git a/docs/design/vcpu-handling.md b/docs/design/vcpu-handling.md
@@ -1,11  1,3 @@
-- [Virtual machine vCPU sizing in Kata Containers](#virtual-machine-vcpu-sizing-in-kata-containers)
-  * [Default number of virtual CPUs](#default-number-of-virtual-cpus)
-  * [Virtual CPUs and Kubernetes pods](#virtual-cpus-and-kubernetes-pods)
-  * [Container lifecycle](#container-lifecycle)
-  * [Container without CPU constraint](#container-without-cpu-constraint)
-  * [Container with CPU constraint](#container-with-cpu-constraint)
-  * [Do not waste resources](#do-not-waste-resources)
-
 # Virtual machine vCPU sizing in Kata Containers
 
 ## Default number of virtual CPUs

diff --git a/docs/design/virtualization.md b/docs/design/virtualization.md
@@ -1,16  1,5 @@
 # Virtualization in Kata Containers
 
-- [Virtualization in Kata Containers](#virtualization-in-kata-containers)
-  - [Mapping container concepts to virtual machine technologies](#mapping-container-concepts-to-virtual-machine-technologies)
-  - [Kata Containers Hypervisor and VMM support](#kata-containers-hypervisor-and-vmm-support)
-    - [QEMU/KVM](#qemukvm)
-      - [Machine accelerators](#machine-accelerators)
-      - [Hotplug devices](#hotplug-devices)
-    - [Firecracker/KVM](#firecrackerkvm)
-    - [Cloud Hypervisor/KVM](#cloud-hypervisorkvm)
-    - [Summary](#summary)
-
-
 Kata Containers, a second layer of isolation is created on top of those provided by traditional namespace-containers. The
 hardware virtualization interface is the basis of this additional layer. Kata will launch a lightweight virtual machine,
 and use the guest’s Linux kernel to create a container workload, or workloads in the case of multi-container pods. In Kubernetes

diff --git a/docs/how-to/README.md b/docs/how-to/README.md
@@ -1,11  1,7 @@
 # Howto Guides
 
-* [Howto Guides](#howto-guides)
-  * [Kubernetes Integration](#kubernetes-integration)
-  * [Hypervisors Integration](#hypervisors-integration)
-  * [Advanced Topics](#advanced-topics)
-
 ## Kubernetes Integration
 
 - [Run Kata containers with `crictl`](run-kata-with-crictl.md)
 - [Run Kata Containers with Kubernetes](run-kata-with-k8s.md)
 - [How to use Kata Containers and Containerd](containerd-kata.md)
@@ -28,6  24,7 @@
 - [Kata Containers with ACRN Hypervisor](how-to-use-kata-containers-with-acrn.md)
 
 ## Advanced Topics
 
 - [How to use Kata Containers with virtio-fs](how-to-use-virtio-fs-with-kata.md)
 - [Setting Sysctls with Kata](how-to-use-sysctls-with-kata.md)
 - [What Is VMCache and How To Enable It](what-is-vm-cache-and-how-do-I-use-it.md)

diff --git a/docs/how-to/containerd-kata.md b/docs/how-to/containerd-kata.md
@@ -1,23  1,5 @@
 # How to use Kata Containers and Containerd
 
-- [Concepts](#concepts)
-    - [Kubernetes `RuntimeClass`](#kubernetes-runtimeclass)
-    - [Containerd Runtime V2 API: Shim V2 API](#containerd-runtime-v2-api-shim-v2-api)
-- [Install](#install)
-    - [Install Kata Containers](#install-kata-containers)
-    - [Install containerd with CRI plugin](#install-containerd-with-cri-plugin)
-    - [Install CNI plugins](#install-cni-plugins)
-    - [Install `cri-tools`](#install-cri-tools)
-- [Configuration](#configuration)
-    - [Configure containerd to use Kata Containers](#configure-containerd-to-use-kata-containers)
-        - [Kata Containers as a `RuntimeClass`](#kata-containers-as-a-runtimeclass)
-        - [Kata Containers as the runtime for untrusted workload](#kata-containers-as-the-runtime-for-untrusted-workload)
-    - [Kata Containers as the default runtime](#kata-containers-as-the-default-runtime)
-    - [Configuration for `cri-tools`](#configuration-for-cri-tools)
-- [Run](#run)
-    - [Launch containers with `ctr` command line](#launch-containers-with-ctr-command-line)
-    - [Launch Pods with `crictl` command line](#launch-pods-with-crictl-command-line)
-
 This document covers the installation and configuration of [containerd](https://containerd.io/) 
 and [Kata Containers](https://katacontainers.io). The containerd provides not only the `ctr`
 command line tool, but also the [CRI](https://kubernetes.io/blog/2016/12/container-runtime-interface-cri-in-kubernetes/) 

diff --git a/docs/how-to/how-to-hotplug-memory-arm64.md b/docs/how-to/how-to-hotplug-memory-arm64.md
@@ -1,9  1,5 @@
 # How to use memory hotplug feature in Kata Containers on arm64
 
-- [Introduction](#introduction)
-- [Install UEFI ROM](#install-uefi-rom)
-- [Run for test](#run-for-test)
-
 ## Introduction
 
 Memory hotplug is a key feature for containers to allocate memory dynamically in deployment.
Original file line number	Diff line number	Diff line change
		@@ -1,4 1,3 @@
		# Kata Containers E2E Flow


		![Kata containers e2e flow](arch-images/katacontainers-e2e-with-bg.jpg)