Merge pull request #1702 from alexandrevilain/docs/add-api-reference

k8s-ci-robot · web-flow · commit 36e94d94995f · 2024-02-28T12:17:47.000-08:00
📖 Add API reference documentation generation
diff --git a/.gitignore b/.gitignore
@@ -173,6 +173,7 @@ sshuttle.pid
 
 # Book
 docs/book/book/
+!docs/book/gen-crd-api-reference-docs/config.json
 
 # venv
 .venv
diff --git a/Makefile b/Makefile
@@ -52,6 +52,7 @@ KUSTOMIZE := $(TOOLS_BIN_DIR)/kustomize
 MOCKGEN := $(TOOLS_BIN_DIR)/mockgen
 RELEASE_NOTES := $(TOOLS_BIN_DIR)/release-notes
 SETUP_ENVTEST := $(TOOLS_BIN_DIR)/setup-envtest
+GEN_CRD_API_REFERENCE_DOCS := $(TOOLS_BIN_DIR)/gen-crd-api-reference-docs
 
 # Kubebuilder
 export KUBEBUILDER_ENVTEST_KUBERNETES_VERSION ?= 1.28.0
@@ -245,7 +246,7 @@ modules: ## Runs go mod to ensure proper vendoring.
 	cd $(TOOLS_DIR); go mod tidy
 
 .PHONY: generate
-generate: generate-controller-gen generate-conversion-gen generate-go generate-manifests ## Generate all generated code
+generate: generate-controller-gen generate-conversion-gen generate-go generate-manifests generate-api-docs ## Generate all generated code
 
 .PHONY: generate-go
 generate-go: $(MOCKGEN)
@@ -282,6 +283,24 @@ generate-manifests: $(CONTROLLER_GEN) ## Generate manifests e.g. CRD, RBAC etc.
 		output:rbac:dir=$(RBAC_ROOT) \
 		rbac:roleName=manager-role
 
+.PHONY: generate-api-docs
+generate-api-docs: $(GEN_CRD_API_REFERENCE_DOCS) ## Generate api documentation
+	$(GEN_CRD_API_REFERENCE_DOCS) \
+		-api-dir=./api/v1beta1 \
+		-config=./docs/book/gen-crd-api-reference-docs/config.json \
+		-template-dir=./docs/book/gen-crd-api-reference-docs/template \
+		-out-file=./docs/book/src/api/v1beta1/api.md
+	$(GEN_CRD_API_REFERENCE_DOCS) \
+		-api-dir=./api/v1alpha7 \
+		-config=./docs/book/gen-crd-api-reference-docs/config.json \
+		-template-dir=./docs/book/gen-crd-api-reference-docs/template \
+		-out-file=./docs/book/src/api/v1alpha7/api.md
+	$(GEN_CRD_API_REFERENCE_DOCS) \
+		-api-dir=./api/v1alpha6 \
+		-config=./docs/book/gen-crd-api-reference-docs/config.json \
+		-template-dir=./docs/book/gen-crd-api-reference-docs/template \
+		-out-file=./docs/book/src/api/v1alpha6/api.md
+
 ## --------------------------------------
 ##@ Docker
 ## --------------------------------------
diff --git a/api/v1alpha6/doc.go b/api/v1alpha6/doc.go
@@ -14,5 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package v1alpha6 contains API Schema definitions for the infrastructure v1alpha6 API group.
+// +kubebuilder:object:generate=true
+// +groupName=infrastructure.cluster.x-k8s.io
 // +k8s:conversion-gen=sigs.k8s.io/cluster-api-provider-openstack/api/v1beta1
 package v1alpha6
diff --git a/api/v1alpha6/groupversion_info.go b/api/v1alpha6/groupversion_info.go
@@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// package v1alpha6 contains API Schema definitions for the infrastructure v1alpha6 API group
-// +kubebuilder:object:generate=true
-// +groupName=infrastructure.cluster.x-k8s.io
 package v1alpha6
 
 import (
diff --git a/api/v1alpha6/openstackcluster_types.go b/api/v1alpha6/openstackcluster_types.go
@@ -212,6 +212,8 @@ type OpenStackClusterStatus struct {
 	FailureMessage *string `json:"failureMessage,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackCluster has been deprecated and will be removed in a future release of the API. Please upgrade."
 // +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
diff --git a/api/v1alpha6/openstackclustertemplate_types.go b/api/v1alpha6/openstackclustertemplate_types.go
@@ -30,6 +30,8 @@ type OpenStackClusterTemplateSpec struct {
 	Template OpenStackClusterTemplateResource `json:"template"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackClusterTemplate has been deprecated and will be removed in a future release of the API. Please upgrade."
 // +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
diff --git a/api/v1alpha6/openstackmachine_types.go b/api/v1alpha6/openstackmachine_types.go
@@ -136,6 +136,8 @@ type OpenStackMachineStatus struct {
 	Conditions clusterv1.Conditions `json:"conditions,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackMachine has been deprecated and will be removed in a future release of the API. Please upgrade."
 // +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm
diff --git a/api/v1alpha6/openstackmachinetemplate_types.go b/api/v1alpha6/openstackmachinetemplate_types.go
@@ -25,6 +25,8 @@ type OpenStackMachineTemplateSpec struct {
 	Template OpenStackMachineTemplateResource `json:"template"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackMachineTemplate has been deprecated and will be removed in a future release of the API. Please upgrade."
 // +kubebuilder:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt
diff --git a/api/v1alpha7/doc.go b/api/v1alpha7/doc.go
@@ -14,5 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package v1alpha7 contains API Schema definitions for the infrastructure v1alpha7 API group.
+// +kubebuilder:object:generate=true
+// +groupName=infrastructure.cluster.x-k8s.io
 // +k8s:conversion-gen=sigs.k8s.io/cluster-api-provider-openstack/api/v1beta1
 package v1alpha7
diff --git a/api/v1alpha7/groupversion_info.go b/api/v1alpha7/groupversion_info.go
@@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// package v1alpha7 contains API Schema definitions for the infrastructure v1alpha7 API group
-// +kubebuilder:object:generate=true
-// +groupName=infrastructure.cluster.x-k8s.io
 package v1alpha7
 
 import (
diff --git a/api/v1alpha7/openstackcluster_types.go b/api/v1alpha7/openstackcluster_types.go
@@ -229,6 +229,8 @@ type OpenStackClusterStatus struct {
 	FailureMessage *string `json:"failureMessage,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
 // +kubebuilder:subresource:status
diff --git a/api/v1alpha7/openstackclustertemplate_types.go b/api/v1alpha7/openstackclustertemplate_types.go
@@ -30,8 +30,10 @@ type OpenStackClusterTemplateSpec struct {
 	Template OpenStackClusterTemplateResource `json:"template"`
 }
 
-//+kubebuilder:object:root=true
-//+kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
+// +genclient
+// +genclient:Namespaced
+// +kubebuilder:object:root=true
+// +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
 
 // OpenStackClusterTemplate is the Schema for the openstackclustertemplates API.
 type OpenStackClusterTemplate struct {
diff --git a/api/v1alpha7/openstackmachine_types.go b/api/v1alpha7/openstackmachine_types.go
@@ -136,6 +136,8 @@ type OpenStackMachineStatus struct {
 	Conditions clusterv1.Conditions `json:"conditions,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm
 // +kubebuilder:subresource:status
diff --git a/api/v1alpha7/openstackmachinetemplate_types.go b/api/v1alpha7/openstackmachinetemplate_types.go
@@ -25,6 +25,8 @@ type OpenStackMachineTemplateSpec struct {
 	Template OpenStackMachineTemplateResource `json:"template"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt
 
diff --git a/api/v1beta1/doc.go b/api/v1beta1/doc.go
@@ -14,4 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package v1beta1 contains API Schema definitions for the infrastructure v1beta1 API group.
+// +kubebuilder:object:generate=true
+// +groupName=infrastructure.cluster.x-k8s.io
 package v1beta1
diff --git a/api/v1beta1/openstackcluster_types.go b/api/v1beta1/openstackcluster_types.go
@@ -235,6 +235,8 @@ type OpenStackClusterStatus struct {
 	FailureMessage *string `json:"failureMessage,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
 // +kubebuilder:storageversion
diff --git a/api/v1beta1/openstackclustertemplate_types.go b/api/v1beta1/openstackclustertemplate_types.go
@@ -30,9 +30,11 @@ type OpenStackClusterTemplateSpec struct {
 	Template OpenStackClusterTemplateResource `json:"template"`
 }
 
-//+kubebuilder:object:root=true
+// +genclient
+// +genclient:Namespaced
+// +kubebuilder:object:root=true
 // +kubebuilder:storageversion
-//+kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
+// +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
 
 // OpenStackClusterTemplate is the Schema for the openstackclustertemplates API.
 type OpenStackClusterTemplate struct {
diff --git a/api/v1beta1/openstackmachine_types.go b/api/v1beta1/openstackmachine_types.go
@@ -146,6 +146,8 @@ type OpenStackMachineStatus struct {
 	Conditions clusterv1.Conditions `json:"conditions,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:storageversion
 // +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm
diff --git a/api/v1beta1/openstackmachinetemplate_types.go b/api/v1beta1/openstackmachinetemplate_types.go
@@ -25,6 +25,8 @@ type OpenStackMachineTemplateSpec struct {
 	Template OpenStackMachineTemplateResource `json:"template"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 // +kubebuilder:storageversion
 // +kubebuilder:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt
diff --git a/docs/book/gen-crd-api-reference-docs/config.json b/docs/book/gen-crd-api-reference-docs/config.json
@@ -0,0 +1,36 @@
+{
+    "hideMemberFields": [
+      "TypeMeta"
+    ],
+    "hideTypePatterns": [
+      "ParseError$",
+      "List$"
+    ],
+    "externalPackages": [
+      {
+        "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
+        "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
+      },
+      {
+        "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Condition$",
+        "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition"
+      },
+      {
+        "typeMatchPrefix": "^sigs\\.k8s\\.io/cluster-api/api/v1beta1",
+        "docsURLTemplate": "https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api@v1.5.1"
+      },
+      {
+        "typeMatchPrefix": "^sigs\\.k8s\\.io/cluster-api/api/v1beta1",
+        "docsURLTemplate": "https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api@v1.5.1"
+      },
+      {
+        "typeMatchPrefix": "^sigs\\.k8s\\.io/cluster-api/errors",
+        "docsURLTemplate": "https://pkg.go.dev/sigs.k8s.io/cluster-api@v1.5.1/errors#{{.TypeIdentifier}}"
+      }
+    ],
+    "typeDisplayNamePrefixOverrides": {
+      "k8s.io/api/": "Kubernetes ",
+      "k8s.io/apimachinery/pkg/apis/": "Kubernetes "
+    },
+    "markdownDisabled": false
+  }
diff --git a/docs/book/gen-crd-api-reference-docs/template/members.tpl b/docs/book/gen-crd-api-reference-docs/template/members.tpl
@@ -0,0 +1,48 @@
+{{ define "members" }}
+
+{{ range .Members }}
+{{ if not (hiddenMember .)}}
+<tr>
+    <td>
+        <code>{{ fieldName . }}</code><br/>
+        <em>
+            {{ if linkForType .Type }}
+                <a href="{{ linkForType .Type}}">
+                    {{ typeDisplayName .Type }}
+                </a>
+            {{ else }}
+                {{ typeDisplayName .Type }}
+            {{ end }}
+        </em>
+    </td>
+    <td>
+        {{ if fieldEmbedded . }}
+            <p>
+                (Members of <code>{{ fieldName . }}</code> are embedded into this type.)
+            </p>
+        {{ end}}
+
+        {{ if isOptionalMember .}}
+            <em>(Optional)</em>
+        {{ end }}
+
+        {{ safe (renderComments .CommentLines) }}
+
+    {{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
+        Refer to the Kubernetes API documentation for the fields of the
+        <code>metadata</code> field.
+    {{ end }}
+
+    {{ if or (eq (fieldName .) "spec") }}
+        <br/>
+        <br/>
+        <table>
+            {{ template "members" .Type }}
+        </table>
+    {{ end }}
+    </td>
+</tr>
+{{ end }}
+{{ end }}
+
+{{ end }}
diff --git a/docs/book/gen-crd-api-reference-docs/template/pkg.tpl b/docs/book/gen-crd-api-reference-docs/template/pkg.tpl
@@ -0,0 +1,37 @@
+{{ define "packages" }}
+
+{{ range .packages }}
+    <h2 id="{{- packageAnchorID . -}}">
+        {{- packageDisplayName . -}}
+    </h2>
+
+    {{ with (index .GoPackages 0 )}}
+        {{ with .DocComments }}
+        <p>
+            {{ safe (renderComments .) }}
+        </p>
+        {{ end }}
+    {{ end }}
+
+    Resource Types:
+    <ul>
+    {{- range (visibleTypes (sortedTypes .Types)) -}}
+        {{ if isExportedType . -}}
+        <li>
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        </li>
+        {{- end }}
+    {{- end -}}
+    </ul>
+
+    {{ range (visibleTypes (sortedTypes .Types))}}
+        {{ template "type" .  }}
+    {{ end }}
+    <hr/>
+{{ end }}
+
+<p><em>
+    Generated with <code>gen-crd-api-reference-docs</code>.
+</em></p>
+
+{{ end }}
diff --git a/docs/book/gen-crd-api-reference-docs/template/type.tpl b/docs/book/gen-crd-api-reference-docs/template/type.tpl
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
diff --git a/docs/book/src/api/index.md b/docs/book/src/api/index.md
diff --git a/docs/book/src/api/v1alpha6/api.md b/docs/book/src/api/v1alpha6/api.md
diff --git a/docs/book/src/api/v1alpha7/api.md b/docs/book/src/api/v1alpha7/api.md
diff --git a/docs/book/src/api/v1beta1/api.md b/docs/book/src/api/v1beta1/api.md
diff --git a/hack/tools/Makefile b/hack/tools/Makefile
diff --git a/hack/tools/go.mod b/hack/tools/go.mod
diff --git a/hack/tools/go.sum b/hack/tools/go.sum
diff --git a/hack/tools/tools.go b/hack/tools/tools.go

Original file line number	Diff line number	Diff line change
`@@ -212,6 +212,8 @@ type OpenStackClusterStatus struct {`
`212`	`212`	FailureMessage *string `json:"failureMessage,omitempty"`
`213`	`213`	`}`
`214`	`214`
	`215`	`+// +genclient`
	`216`	`+// +genclient:Namespaced`
`215`	`217`	`// +kubebuilder:object:root=true`
`216`	`218`	`// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackCluster has been deprecated and will be removed in a future release of the API. Please upgrade."`
`217`	`219`	`// +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc`
Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,8 @@ type OpenStackClusterTemplateSpec struct {`
`30`	`30`	Template OpenStackClusterTemplateResource `json:"template"`
`31`	`31`	`}`
`32`	`32`
	`33`	`+// +genclient`
	`34`	`+// +genclient:Namespaced`
`33`	`35`	`// +kubebuilder:object:root=true`
`34`	`36`	`// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackClusterTemplate has been deprecated and will be removed in a future release of the API. Please upgrade."`
`35`	`37`	`// +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct`
Original file line number	Diff line number	Diff line change
`@@ -136,6 +136,8 @@ type OpenStackMachineStatus struct {`
`136`	`136`	Conditions clusterv1.Conditions `json:"conditions,omitempty"`
`137`	`137`	`}`
`138`	`138`
	`139`	`+// +genclient`
	`140`	`+// +genclient:Namespaced`
`139`	`141`	`// +kubebuilder:object:root=true`
`140`	`142`	`// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackMachine has been deprecated and will be removed in a future release of the API. Please upgrade."`
`141`	`143`	`// +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,8 @@ type OpenStackMachineTemplateSpec struct {`
`25`	`25`	Template OpenStackMachineTemplateResource `json:"template"`
`26`	`26`	`}`
`27`	`27`
	`28`	`+// +genclient`
	`29`	`+// +genclient:Namespaced`
`28`	`30`	`// +kubebuilder:object:root=true`
`29`	`31`	`// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackMachineTemplate has been deprecated and will be removed in a future release of the API. Please upgrade."`
`30`	`32`	`// +kubebuilder:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt`