Merge pull request #1150 from dongwangdw/setup-doctoc

issue-934: Add doctoc for docs updating

Author: k8s-ci-robot

CONTRIBUTING.md

@@ -1,4 +1,27 @@
 # Contributing Guidelines
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Contributor License Agreements](#contributor-license-agreements)
+- [Finding Things That Need Help](#finding-things-that-need-help)
+- [Contributing a Patch](#contributing-a-patch)
+- [Backporting a Patch](#backporting-a-patch)
+  - [Merge Approval](#merge-approval)
+  - [Google Doc Viewing Permissions](#google-doc-viewing-permissions)
+  - [Issue and Pull Request Management](#issue-and-pull-request-management)
+- [Cloud Provider Developer Guide](#cloud-provider-developer-guide)
+  - [Overview](#overview)
+  - [Resources](#resources)
+  - [Boostrapping](#boostrapping)
+  - [A new Machine can be created in a declarative way](#a-new-machine-can-be-created-in-a-declarative-way)
+    - [Configurable Machine Setup](#configurable-machine-setup)
+      - [GCE Implementation](#gce-implementation)
+  - [A specific Machine can be deleted, freeing external resources associated with it.](#a-specific-machine-can-be-deleted-freeing-external-resources-associated-with-it)
+  - [A specific Machine can be upgraded or downgraded](#a-specific-machine-can-be-upgraded-or-downgraded)
+- [Support Channels](#support-channels)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 Read the following guide if you're interested in contributing to cluster-api.
 

Makefile

@@ -200,6 +200,7 @@ verify:
 	./hack/verify-boilerplate.sh
 	./hack/verify-clientset.sh
 	./hack/verify-bazel.sh
+	./hack/verify-doctoc.sh
 
 .PHONY: clean-book
 clean-book: ## Remove all generated GitBook files

README.md

@@ -1,4 +1,19 @@
 # Cluster API
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [What is the Cluster API?](#what-is-the-cluster-api)
+- [Getting Started](#getting-started)
+  - [Resources](#resources)
+  - [Prerequisites](#prerequisites)
+  - [Using `clusterctl` to create a cluster](#using-clusterctl-to-create-a-cluster)
+  - [How does Cluster API compare to Kubernetes Cloud Providers?](#how-does-cluster-api-compare-to-kubernetes-cloud-providers)
+- [Get involved!](#get-involved)
+- [Provider Implementations](#provider-implementations)
+- [API Adoption](#api-adoption)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 ## What is the Cluster API?
 
 The Cluster API is a Kubernetes project to bring declarative, Kubernetes-style

cmd/clusterctl/README.md

@@ -1,4 +1,20 @@
 # clusterctl
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Limitations](#limitations)
+  - [Creating a cluster](#creating-a-cluster)
+  - [Interacting with your cluster](#interacting-with-your-cluster)
+    - [Scaling your cluster](#scaling-your-cluster)
+    - [Upgrading your cluster](#upgrading-your-cluster)
+    - [Node repair](#node-repair)
+  - [Deleting a cluster](#deleting-a-cluster)
+- [Contributing](#contributing)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 `clusterctl` is the SIG-cluster-lifecycle sponsored tool that implements the Cluster API.
 

docs/developer/releasing.md

@@ -1,4 +1,15 @@
 # Releasing
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Output](#output)
+  - [Expected artifacts](#expected-artifacts)
+  - [Artifact locations](#artifact-locations)
+- [Process](#process)
+  - [Permissions](#permissions)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Output
 

docs/how-to-use-clusterctl.md

@@ -1,4 +1,13 @@
 # Using `clusterctl` to create a cluster from scratch
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [What is `clusterctl`?](#what-is-clusterctl)
+- [Creating a cluster](#creating-a-cluster)
+  - [Creating a workload cluster using the management cluster](#creating-a-workload-cluster-using-the-management-cluster)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 This document provides an overview of how `clusterctl` works and explains how one can use `clusterctl`
 to create a Kubernetes cluster from scratch.

docs/proposals/20181121-machine-api.md

@@ -1,6 +1,20 @@
 Minimalistic Machines API
 =========================
-
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+ 
+
+- [Capabilities](#capabilities)
+- [Proposal](#proposal)
+- [In-place vs. Replace](#in-place-vs-replace)
+- [Omitted Capabilities](#omitted-capabilities)
+  - [A provider-agnostic mechanism to request new nodes](#a-provider-agnostic-mechanism-to-request-new-nodes)
+  - [Dynamic API endpoint](#dynamic-api-endpoint)
+- [Conditions](#conditions)
+- [Types](#types)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+ 
 This proposal is for a minimalistic start to a new Machines API, as part of the
 overall Cluster API project. It is intended to live outside of core Kubernetes
 and add optional machine management features to Kubernetes clusters.

docs/proposals/20190610-machine-states-preboot-bootstrapping.md

@@ -1,5 +1,75 @@
 ---
 title: Machine States & Preboot Bootstrapping
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Machine States & Preboot Bootstrapping](#machine-states--preboot-bootstrapping)
+  - [Table of Contents](#table-of-contents)
+  - [Glossary](#glossary)
+  - [Summary](#summary)
+  - [Motivation](#motivation)
+    - [Goals](#goals)
+    - [Non-Goals/Future Work](#non-goalsfuture-work)
+  - [Proposal](#proposal)
+    - [Data model changes](#data-model-changes)
+  - [States and transitions](#states-and-transitions)
+    - [Pending](#pending)
+      - [Transition Conditions](#transition-conditions)
+      - [Expectations](#expectations)
+    - [Provisioning](#provisioning)
+      - [Transition Conditions](#transition-conditions-1)
+      - [Expectations](#expectations-1)
+    - [Provisioned](#provisioned)
+      - [Transition Conditions](#transition-conditions-2)
+      - [Expectations](#expectations-2)
+    - [Running](#running)
+      - [Transition Conditions](#transition-conditions-3)
+      - [Expectations](#expectations-3)
+    - [Deleting](#deleting)
+      - [Transition Conditions](#transition-conditions-4)
+      - [Expectations](#expectations-4)
+    - [Deleted](#deleted)
+      - [Transition Conditions](#transition-conditions-5)
+      - [Expectations](#expectations-5)
+    - [Failed](#failed)
+      - [Transition Conditions](#transition-conditions-6)
+      - [Expectations](#expectations-6)
+    - [Sequence diagram: User creates a machine with Kubeadm bootstrapper.](#sequence-diagram-user-creates-a-machine-with-kubeadm-bootstrapper)
+    - [User Stories](#user-stories)
+      - [As a Kubernetes operator, I’d like to provide custom bootstrap data without the use of a Kubernetes controller.](#as-a-kubernetes-operator-id-like-to-provide-custom-bootstrap-data-without-the-use-of-a-kubernetes-controller)
+      - [As a Kubernetes operator, I’d like to monitor the progress of fulfilling a Machine and understand what errors, if any, have been reported by the controllers involved.](#as-a-kubernetes-operator-id-like-to-monitor-the-progress-of-fulfilling-a-machine-and-understand-what-errors-if-any-have-been-reported-by-the-controllers-involved)
+      - [As an infrastructure provider author, I would like to build the fewest number of components possible to support the full cluster-api.](#as-an-infrastructure-provider-author-i-would-like-to-build-the-fewest-number-of-components-possible-to-support-the-full-cluster-api)
+      - [As an infrastructure provider author, I would like to take advantage of the kubernetes API to provide validation for provider-specific data needed to provision a machine.](#as-an-infrastructure-provider-author-i-would-like-to-take-advantage-of-the-kubernetes-api-to-provide-validation-for-provider-specific-data-needed-to-provision-a-machine)
+      - [As an infrastructure provider author, I would like to build a controller to manage provisioning machines using tools of my own choosing.](#as-an-infrastructure-provider-author-i-would-like-to-build-a-controller-to-manage-provisioning-machines-using-tools-of-my-own-choosing)
+      - [As an infrastructure provider author, I would like to build a controller to manage provisioning machines without being restricted to a CRUD API.](#as-an-infrastructure-provider-author-i-would-like-to-build-a-controller-to-manage-provisioning-machines-without-being-restricted-to-a-crud-api)
+      - [As an infrastructure provider consumer, I would like to have validation for the provider-specific data I need to give the system to have it provision a machine.](#as-an-infrastructure-provider-consumer-i-would-like-to-have-validation-for-the-provider-specific-data-i-need-to-give-the-system-to-have-it-provision-a-machine)
+    - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
+      - [Machine Controller Role](#machine-controller-role)
+      - [Machine Controller dynamic watchers](#machine-controller-dynamic-watchers)
+      - [Object References, Templates, MachineSets and MachineDeployments](#object-references-templates-machinesets-and-machinedeployments)
+      - [Controllers and the single responsibility approach](#controllers-and-the-single-responsibility-approach)
+      - [Remote references and accessing a workload cluster](#remote-references-and-accessing-a-workload-cluster)
+      - [The “Phase” field and its role](#the-phase-field-and-its-role)
+      - [Showing a status summary to users](#showing-a-status-summary-to-users)
+    - [Risks and Mitigations](#risks-and-mitigations)
+      - [State transitions are inflexible](#state-transitions-are-inflexible)
+      - [Machine Controller can access any machine or cluster in any namespace](#machine-controller-can-access-any-machine-or-cluster-in-any-namespace)
+      - [Certificates and tokens are exposed in plaintext](#certificates-and-tokens-are-exposed-in-plaintext)
+      - [Bootstrap data cannot be merged](#bootstrap-data-cannot-be-merged)
+      - [MachineClass is deprecated and will be revisited later](#machineclass-is-deprecated-and-will-be-revisited-later)
+  - [Design Details](#design-details)
+    - [Test Plan](#test-plan)
+    - [Graduation Criteria](#graduation-criteria)
+    - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+    - [Version Skew Strategy](#version-skew-strategy)
+  - [Implementation History](#implementation-history)
+  - [Drawbacks](#drawbacks)
+  - [Alternatives](#alternatives)
+      - [Object References, Templates, MachineSets and MachineDeployments](#object-references-templates-machinesets-and-machinedeployments-1)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 authors:
   - "@ncdc"
   - "@vincepri"

docs/proposals/YYYYMMDD-template.md

@@ -1,5 +1,36 @@
 ---
 title: proposal Template
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Title](#title)
+  - [Table of Contents](#table-of-contents)
+  - [Summary](#summary)
+  - [Motivation](#motivation)
+    - [Goals](#goals)
+    - [Non-Goals](#non-goals)
+  - [Proposal](#proposal)
+    - [User Stories [optional]](#user-stories-optional)
+      - [Story 1](#story-1)
+      - [Story 2](#story-2)
+    - [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional)
+    - [Risks and Mitigations](#risks-and-mitigations)
+  - [Design Details](#design-details)
+    - [Test Plan](#test-plan)
+    - [Graduation Criteria](#graduation-criteria)
+      - [Examples](#examples)
+        - [Alpha -> Beta Graduation](#alpha---beta-graduation)
+        - [Beta -> GA Graduation](#beta---ga-graduation)
+        - [Removing a deprecated flag](#removing-a-deprecated-flag)
+    - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+    - [Version Skew Strategy](#version-skew-strategy)
+  - [Implementation History](#implementation-history)
+  - [Drawbacks [optional]](#drawbacks-optional)
+  - [Alternatives [optional]](#alternatives-optional)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 authors:
   - "@janedoe"
 reviewers:

docs/proposals/images/machine-states-preboot/README.md

@@ -1,4 +1,11 @@
 # Figures with PlantUML
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Generating figures](#generating-figures)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 Most of the figures for this proposal are generated with [PlantUML](http://plantuml.com/), an [open-source](https://sourceforge.net/projects/plantuml/) tool that can generate sequence, use case, class, activity, state, object, and other kinds of UML digrams.