Add API reference documentation generation

alexandrevilain · alexandrevilain · commit e80879cfabfe · 2024-02-22T11:29:18.000+01:00
Signed-off-by: alexandre.vilain &lt;alexandre.vilain@corp.ovh.com&gt;
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
@@ -248,6 +249,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)
@@ -279,6 +281,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/v1alpha8 \
+		-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/v1alpha8/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/v1alpha8
 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,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/v1alpha8
 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,11 @@ 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:storageversion
+// +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
@@ -36,6 +36,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/api/v1alpha8/doc.go b/api/v1alpha8/doc.go
@@ -14,4 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// package v1alpha8 contains API Schema definitions for the infrastructure v1alpha8 API group
+// +kubebuilder:object:generate=true
+// +groupName=infrastructure.cluster.x-k8s.io
 package v1alpha8
diff --git a/api/v1alpha8/groupversion_info.go b/api/v1alpha8/groupversion_info.go
@@ -13,10 +13,6 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
-
-// package v1alpha8 contains API Schema definitions for the infrastructure v1alpha8 API group
-// +kubebuilder:object:generate=true
-// +groupName=infrastructure.cluster.x-k8s.io
 package v1alpha8
 
 import (
diff --git a/api/v1alpha8/openstackcluster_types.go b/api/v1alpha8/openstackcluster_types.go
@@ -242,6 +242,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/v1alpha8/openstackclustertemplate_types.go b/api/v1alpha8/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/v1alpha8/openstackmachine_types.go b/api/v1alpha8/openstackmachine_types.go
@@ -143,6 +143,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/v1alpha8/openstackmachinetemplate_types.go b/api/v1alpha8/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/config/crd/bases/infrastructure.cluster.x-k8s.io_openstackclustertemplates.yaml b/config/crd/bases/infrastructure.cluster.x-k8s.io_openstackclustertemplates.yaml
@@ -2227,7 +2227,7 @@ spec:
             type: object
         type: object
     served: true
-    storage: false
+    storage: true
   - name: v1alpha8
     schema:
       openAPIV3Schema:
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/v1alpha8/api.md b/docs/book/src/api/v1alpha8/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`