Add API reference documentation generation

alexandrevilain · alexandrevilain · commit 0b4f2297b330 · 2023-10-05T10:08:49.000+02:00
Signed-off-by: alexandre.vilain &lt;alexandre.vilain@corp.ovh.com&gt;
diff --git a/Makefile b/Makefile
@@ -52,6 +52,13 @@ 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
+
+# Setup-envtest
+SETUP_ENVTEST_VER := v0.0.0-20221201045826-d9912251cd81
+SETUP_ENVTEST_BIN := setup-envtest
+SETUP_ENVTEST := $(abspath $(TOOLS_BIN_DIR)/$(SETUP_ENVTEST_BIN)-$(SETUP_ENVTEST_VER))
+SETUP_ENVTEST_PKG := sigs.k8s.io/controller-runtime/tools/setup-envtest
 
 # Kubebuilder
 export KUBEBUILDER_ENVTEST_KUBERNETES_VERSION ?= 1.25.0
@@ -247,6 +254,7 @@ modules: ## Runs go mod to ensure proper vendoring.
 generate: ## Generate code
 	$(MAKE) generate-go
 	$(MAKE) generate-manifests
+	$(MAKE) generate-api-docs
 
 .PHONY: generate-go
 generate-go: $(MOCKGEN)
@@ -275,6 +283,19 @@ 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/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/v1alpha7
 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:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
 // +kubebuilder:subresource:status
diff --git a/api/v1alpha6/openstackclustertemplate_types.go b/api/v1alpha6/openstackclustertemplate_types.go
@@ -41,6 +41,8 @@ type OpenStackClusterTemplate struct {
 	Spec OpenStackClusterTemplateSpec `json:"spec,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 //+kubebuilder:object:root=true
 
 // OpenStackClusterTemplateList contains a list of OpenStackClusterTemplate.
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:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm
 // +kubebuilder:subresource:status
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:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt
 
diff --git a/api/v1alpha7/doc.go b/api/v1alpha7/doc.go
@@ -14,4 +14,7 @@ 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
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
@@ -222,6 +222,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/v1alpha7/openstackclustertemplate_types.go b/api/v1alpha7/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/v1alpha7/openstackmachine_types.go b/api/v1alpha7/openstackmachine_types.go
@@ -134,6 +134,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/v1alpha7/openstackmachinetemplate_types.go b/api/v1alpha7/openstackmachinetemplate_types.go
@@ -37,6 +37,8 @@ type OpenStackMachineTemplate struct {
 	Spec OpenStackMachineTemplateSpec `json:"spec,omitempty"`
 }
 
+// +genclient
+// +genclient:Namespaced
 // +kubebuilder:object:root=true
 
 // OpenStackMachineTemplateList contains a list of OpenStackMachineTemplate.
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,38 @@
+{{ 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>
+    {{ with .gitCommit }} on git commit <code>{{ . }}</code>{{end}}.
+</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
@@ -0,0 +1,81 @@
+{{ define "type" }}
+
+<h3 id="{{ anchorIDForType . }}">
+    {{- .Name.Name }}
+    {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
+</h3>
+{{ with (typeReferences .) }}
+    <p>
+        (<em>Appears on:</em>
+        {{- $prev := "" -}}
+        {{- range . -}}
+            {{- if $prev -}}, {{ end -}}
+            {{ $prev = . }}
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        {{- end -}}
+        )
+    </p>
+{{ end }}
+
+<p>
+    {{ safe (renderComments .CommentLines) }}
+</p>
+
+{{ with (constantsOfType .) }}
+<table>
+    <thead>
+        <tr>
+            <th>Value</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+      {{- range . -}}
+      <tr>
+        {{- /*
+            renderComments implicitly creates a <p> element, so we
+            add one to the display name as well to make the contents
+            of the two cells align evenly.
+        */ -}}
+        <td><p>{{ typeDisplayName . }}</p></td>
+        <td>{{ safe (renderComments .CommentLines) }}</td>
+      </tr>
+      {{- end -}}
+    </tbody>
+</table>
+{{ end }}
+
+{{ if .Members }}
+<table>
+    <thead>
+        <tr>
+            <th>Field</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        {{ if isExportedType . }}
+        <tr>
+            <td>
+                <code>apiVersion</code><br/>
+                string</td>
+            <td>
+                <code>
+                    {{apiGroup .}}
+                </code>
+            </td>
+        </tr>
+        <tr>
+            <td>
+                <code>kind</code><br/>
+                string
+            </td>
+            <td><code>{{.Name.Name}}</code></td>
+        </tr>
+        {{ end }}
+        {{ template "members" .}}
+    </tbody>
+</table>
+{{ end }}
+
+{{ end }}
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -11,5 +11,8 @@
         - [v1alpha4 to v1alpha5](./topics/crd-changes/v1alpha4-to-v1alpha5.md)
         - [v1alpha5 to v1alpha6](./topics/crd-changes/v1alpha5-to-v1alpha6.md)
         - [v1alpha6 to v1alpha7](./topics/crd-changes/v1alpha6-to-v1alpha7.md)
+- [API reference](./api/index.md)
+    - [v1alpha6](./api/v1alpha6/api.md)
+    - [v1alpha7](./api/v1alpha7/api.md)
 - [Development](./development/development.md)
 - [Hacking CI](./development/ci.md)
diff --git a/docs/book/src/api/index.md b/docs/book/src/api/index.md
@@ -0,0 +1 @@
+# API reference
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/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:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc`
`217`	`219`	`// +kubebuilder:subresource:status`
Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,8 @@ type OpenStackClusterTemplate struct {`
`41`	`41`	Spec OpenStackClusterTemplateSpec `json:"spec,omitempty"`
`42`	`42`	`}`
`43`	`43`
	`44`	`+// +genclient`
	`45`	`+// +genclient:Namespaced`
`44`	`46`	`//+kubebuilder:object:root=true`
`45`	`47`
`46`	`48`	`// OpenStackClusterTemplateList contains a list of OpenStackClusterTemplate.`
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:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm`
`141`	`143`	`// +kubebuilder:subresource:status`
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:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt`
`30`	`32`
Original file line number	Diff line number	Diff line change
`@@ -222,6 +222,8 @@ type OpenStackClusterStatus struct {`
`222`	`222`	FailureMessage *string `json:"failureMessage,omitempty"`
`223`	`223`	`}`
`224`	`224`
	`225`	`+// +genclient`
	`226`	`+// +genclient:Namespaced`
`225`	`227`	`// +kubebuilder:object:root=true`
`226`	`228`	`// +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc`
`227`	`229`	`// +kubebuilder:storageversion`