Fix doctoc detection in verify-doctoc.sh

Signed-off-by: Stefan Büringer buringerst@vmware.com
kubernetes-sigs · Aug 3, 2023 · aa605ee · aa605ee
1 parent 1567f68
commit aa605ee
Show file tree

Hide file tree

Showing 38 changed files with 1,095 additions and 969 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,6 +11,7 @@
   - [CLIs](#clis)
 - [Branches](#branches)
   - [Support and guarantees](#support-and-guarantees)
+  - [Removal of v1alpha3 & v1alpha4 apiVersions](#removal-of-v1alpha3--v1alpha4-apiversions)
 - [Contributing a Patch](#contributing-a-patch)
 - [Documentation changes](#documentation-changes)
 - [Releases](#releases)

diff --git a/Makefile b/Makefile
@@ -503,6 +503,10 @@ generate-modules: ## Run go mod tidy to ensure modules are up to date
 	cd $(TOOLS_DIR); go mod tidy
 	cd $(TEST_DIR); go mod tidy
 
+.PHONY: generate-doctoc
+generate-doctoc:
+	TRACE=$(TRACE) ./hack/generate-doctoc.sh
+
 .PHONY: generate-e2e-templates
 generate-e2e-templates: $(KUSTOMIZE) $(addprefix generate-e2e-templates-, v1.0 v1.3 v1.4 main) ## Generate cluster templates for all versions
 
@@ -596,7 +600,7 @@ APIDIFF_OLD_COMMIT ?= $(shell git rev-parse origin/main)
 apidiff: $(GO_APIDIFF) ## Check for API differences
 	$(GO_APIDIFF) $(APIDIFF_OLD_COMMIT) --print-compatible
 
-ALL_VERIFY_CHECKS = doctoc boilerplate shellcheck tiltfile modules gen conversions capi-book-summary
+ALL_VERIFY_CHECKS = doctoc boilerplate shellcheck tiltfile modules gen conversions doctoc capi-book-summary
 
 .PHONY: verify
 verify: $(addprefix verify-,$(ALL_VERIFY_CHECKS)) lint-dockerfiles ## Run all verify-* targets
@@ -623,9 +627,11 @@ verify-gen: generate  ## Verify go generated files are up to date
 verify-conversions: $(CONVERSION_VERIFIER)  ## Verifies expected API conversion are in place
 	$(CONVERSION_VERIFIER)
 
-.PHONY: verify-doctoc
-verify-doctoc:
-	TRACE=$(TRACE) ./hack/verify-doctoc.sh
+verify-doctoc: generate-doctoc
+	@if !(git diff --quiet HEAD); then \
+		git diff; \
+		echo "doctoc is out of date, run make generate-doctoc"; exit 1; \
+	fi
 
 .PHONY: verify-capi-book-summary
 verify-capi-book-summary:

diff --git a/docs/proposals/20181121-machine-api.md b/docs/proposals/20181121-machine-api.md
@@ -3,7 +3,6 @@ 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)

diff --git a/docs/proposals/20190610-machine-states-preboot-bootstrapping.md b/docs/proposals/20190610-machine-states-preboot-bootstrapping.md
@@ -18,62 +18,65 @@ status: implemented
 
 ## Table of Contents
 
-* [Machine States &amp; 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)
-    * [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)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [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)
+  - [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 -->
 
 ## Glossary
 

diff --git a/docs/proposals/20190709-cluster-spec-crds.md b/docs/proposals/20190709-cluster-spec-crds.md
@@ -18,41 +18,44 @@ see-also:
 
 ## Table of Contents
 
-   * [Cluster Spec &amp; Status CRDs](#cluster-spec--status-crds)
-      * [Table of Contents](#table-of-contents)
-      * [Summary](#summary)
-      * [Motivation](#motivation)
-         * [Goals](#goals)
-         * [Non-Goals/Future Work](#non-goalsfuture-work)
-      * [Proposal](#proposal)
-         * [Data Model changes](#data-model-changes)
-         * [Controller collaboration](#controller-collaboration)
-         * [States and Transitions](#states-and-transitions)
-            * [Pending](#pending)
-               * [Conditions](#conditions)
-               * [Expectations](#expectations)
-            * [Provisioning](#provisioning)
-               * [Transition Conditions](#transition-conditions)
-               * [Expectations](#expectations-1)
-            * [Provisioned](#provisioned)
-               * [Transition Conditions](#transition-conditions-1)
-               * [Expectations](#expectations-2)
-         * [User Stories](#user-stories)
-            * [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 cluster infrastructure.](#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-cluster-infrastructure)
-            * [As an infrastructure provider author, I would like to build a controller to manage provisioning cluster infrastructure using tools of my own choosing.](#as-an-infrastructure-provider-author-i-would-like-to-build-a-controller-to-manage-provisioning-cluster-infrastructure-using-tools-of-my-own-choosing)
-            * [As an infrastructure provider author, I would like to build a controller to manage provisioning clusters without being restricted to a CRUD API.](#as-an-infrastructure-provider-author-i-would-like-to-build-a-controller-to-manage-provisioning-clusters-without-being-restricted-to-a-crud-api)
-         * [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
-            * [Role of Cluster Controller](#role-of-cluster-controller)
-            * [Cluster Controller dynamic watchers](#cluster-controller-dynamic-watchers)
-         * [Risks and Mitigations](#risks-and-mitigations)
-      * [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 [optional]](#drawbacks-optional)
-      * [Alternatives [optional]](#alternatives-optional)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals/Future Work](#non-goalsfuture-work)
+- [Proposal](#proposal)
+  - [Data Model changes](#data-model-changes)
+  - [Controller collaboration](#controller-collaboration)
+  - [States and Transitions](#states-and-transitions)
+    - [Pending](#pending)
+      - [Conditions](#conditions)
+      - [Expectations](#expectations)
+    - [Provisioning](#provisioning)
+      - [Transition Conditions](#transition-conditions)
+      - [Expectations](#expectations-1)
+    - [Provisioned](#provisioned)
+      - [Transition Conditions](#transition-conditions-1)
+      - [Expectations](#expectations-2)
+  - [User Stories](#user-stories)
+    - [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 cluster infrastructure.](#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-cluster-infrastructure)
+    - [As an infrastructure provider author, I would like to build a controller to manage provisioning cluster infrastructure using tools of my own choosing.](#as-an-infrastructure-provider-author-i-would-like-to-build-a-controller-to-manage-provisioning-cluster-infrastructure-using-tools-of-my-own-choosing)
+    - [As an infrastructure provider author, I would like to build a controller to manage provisioning clusters without being restricted to a CRUD API.](#as-an-infrastructure-provider-author-i-would-like-to-build-a-controller-to-manage-provisioning-clusters-without-being-restricted-to-a-crud-api)
+  - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
+    - [Role of Cluster Controller](#role-of-cluster-controller)
+    - [Cluster Controller dynamic watchers](#cluster-controller-dynamic-watchers)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [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 [optional]](#drawbacks-optional)
+- [Alternatives [optional]](#alternatives-optional)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Summary
 

diff --git a/docs/proposals/20190919-machinepool-api.md b/docs/proposals/20190919-machinepool-api.md
@@ -1,9 +1,23 @@
 ---
 title: MachinePool API
+authors:
+- "@juan-lee"
+- "@CecileRobertMichon"
+  reviewers:
+- "@detiber"
+- "@justaugustus"
+- "@ncdc"
+- "@vincepri"
+  creation-date: 2019-09-19
+  last-updated: 2019-11-24
+  replaces:
+- [cluster-api-provider-azure Proposal](https://docs.google.com/document/d/1nbOqCIC0-ezdMXubZIV6EQrzD0QYPrpcdCBB4oSjWeQ/edit)
+  status: provisional
+---
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-
 - [MachinePool API](#machinepool-api)
   - [Glossary](#glossary)
   - [Summary](#summary)
@@ -51,20 +65,6 @@ title: MachinePool API
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-authors:
-  - "@juan-lee"
-  - "@CecileRobertMichon"
-reviewers:
-  - "@detiber"
-  - "@justaugustus"
-  - "@ncdc"
-  - "@vincepri"
-creation-date: 2019-09-19
-last-updated: 2019-11-24
-replaces:
-  - [cluster-api-provider-azure Proposal](https://docs.google.com/document/d/1nbOqCIC0-ezdMXubZIV6EQrzD0QYPrpcdCBB4oSjWeQ/edit)
-status: provisional
----
 
 # MachinePool API
 

diff --git a/docs/proposals/20191016-clusterctl-redesign.md b/docs/proposals/20191016-clusterctl-redesign.md
@@ -21,30 +21,34 @@ status: implementable
 
 ## Table of Contents
 
-- [Table of Contents](#table-of-contents)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
 - [Glossary](#glossary)
 - [Summary](#summary)
 - [Motivation](#motivation)
-    - [Goals](#goals)
-    - [Non-Goals/Future Work](#non-goalsfuture-work)
+  - [Goals](#goals)
+  - [Non-Goals/Future Work](#non-goalsfuture-work)
 - [Proposal](#proposal)
-    - [Preconditions](#preconditions)
-    - [User Stories](#user-stories)
-        - [Initial Deployment](#initial-deployment)
-        - [Day Two Operations “Lifecycle Management”](#day-two-operations-lifecycle-management)
-        - [Target Cluster Pivot Management](#target-cluster-pivot-management)
-        - [Provider Enablement](#provider-enablement)
-    - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
-        - [Init sequence](#init-sequence)
-        - [Day 2 operations](#day-2-operations)
-    - [Risks and Mitigations](#risks-and-mitigations)
+  - [Preconditions](#preconditions)
+  - [User Stories](#user-stories)
+    - [Initial Deployment](#initial-deployment)
+    - [Day Two Operations “Lifecycle Management”](#day-two-operations-lifecycle-management)
+    - [Target Cluster Pivot Management](#target-cluster-pivot-management)
+    - [Provider Enablement](#provider-enablement)
+  - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
+    - [Init sequence](#init-sequence)
+    - [Day 2 operations](#day-2-operations)
+  - [Risks and Mitigations](#risks-and-mitigations)
 - [Upgrade Strategy](#upgrade-strategy)
 - [Additional Details](#additional-details)
-    - [Test Plan [optional]](#test-plan-optional)
-    - [Graduation Criteria [optional]](#graduation-criteria-optional)
-    - [Version Skew Strategy](#version-skew-strategy)
+  - [Test Plan [optional]](#test-plan-optional)
+  - [Graduation Criteria [optional]](#graduation-criteria-optional)
+  - [Version Skew Strategy](#version-skew-strategy)
 - [Implementation History](#implementation-history)
 
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Glossary
 
 Refer to the [Cluster API Book Glossary](https://cluster-api.sigs.k8s.io/reference/glossary.html).

diff --git a/docs/proposals/20191016-e2e-test-framework.md b/docs/proposals/20191016-e2e-test-framework.md
@@ -27,7 +27,6 @@ superseded-by: []
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-
 - [Glossary](#glossary)
 - [Summary](#summary)
 - [Motivation](#motivation)