Skip to content

Commit af5545c

Browse files
alexandrevilainalexandrevilain
committed
Add API reference documentation generation
Signed-off-by: alexandre.vilain <[email protected]>
1 parent a405eeb commit af5545c

32 files changed

+13540
-11
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,7 @@ sshuttle.pid
173173

174174
# Book
175175
docs/book/book/
176+
!docs/book/gen-crd-api-reference-docs/config.json
176177

177178
# venv
178179
.venv

‎Makefile

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ KUSTOMIZE := $(TOOLS_BIN_DIR)/kustomize
5252
MOCKGEN := $(TOOLS_BIN_DIR)/mockgen
5353
RELEASE_NOTES := $(TOOLS_BIN_DIR)/release-notes
5454
SETUP_ENVTEST := $(TOOLS_BIN_DIR)/setup-envtest
55+
GEN_CRD_API_REFERENCE_DOCS := $(TOOLS_BIN_DIR)/gen-crd-api-reference-docs
5556

5657
# Kubebuilder
5758
export KUBEBUILDER_ENVTEST_KUBERNETES_VERSION ?= 1.28.0
@@ -245,7 +246,7 @@ modules: ## Runs go mod to ensure proper vendoring.
245246
cd $(TOOLS_DIR); go mod tidy
246247

247248
.PHONY: generate
248-
generate: generate-controller-gen generate-conversion-gen generate-go generate-manifests ## Generate all generated code
249+
generate: generate-controller-gen generate-conversion-gen generate-go generate-manifests generate-api-docs ## Generate all generated code
249250

250251
.PHONY: generate-go
251252
generate-go: $(MOCKGEN)
@@ -282,6 +283,24 @@ generate-manifests: $(CONTROLLER_GEN) ## Generate manifests e.g. CRD, RBAC etc.
282283
output:rbac:dir=$(RBAC_ROOT) \
283284
rbac:roleName=manager-role
284285

286+
.PHONY: generate-api-docs
287+
generate-api-docs: $(GEN_CRD_API_REFERENCE_DOCS) ## Generate api documentation
288+
$(GEN_CRD_API_REFERENCE_DOCS) \
289+
-api-dir=./api/v1beta1 \
290+
-config=./docs/book/gen-crd-api-reference-docs/config.json \
291+
-template-dir=./docs/book/gen-crd-api-reference-docs/template \
292+
-out-file=./docs/book/src/api/v1beta1/api.md
293+
$(GEN_CRD_API_REFERENCE_DOCS) \
294+
-api-dir=./api/v1alpha7 \
295+
-config=./docs/book/gen-crd-api-reference-docs/config.json \
296+
-template-dir=./docs/book/gen-crd-api-reference-docs/template \
297+
-out-file=./docs/book/src/api/v1alpha7/api.md
298+
$(GEN_CRD_API_REFERENCE_DOCS) \
299+
-api-dir=./api/v1alpha6 \
300+
-config=./docs/book/gen-crd-api-reference-docs/config.json \
301+
-template-dir=./docs/book/gen-crd-api-reference-docs/template \
302+
-out-file=./docs/book/src/api/v1alpha6/api.md
303+
285304
## --------------------------------------
286305
##@ Docker
287306
## --------------------------------------

‎api/v1alpha6/doc.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,8 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17+
// Package v1alpha6 contains API Schema definitions for the infrastructure v1alpha6 API group.
18+
// +kubebuilder:object:generate=true
19+
// +groupName=infrastructure.cluster.x-k8s.io
1720
// +k8s:conversion-gen=sigs.k8s.io/cluster-api-provider-openstack/api/v1beta1
1821
package v1alpha6

‎api/v1alpha6/groupversion_info.go

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17-
// package v1alpha6 contains API Schema definitions for the infrastructure v1alpha6 API group
18-
// +kubebuilder:object:generate=true
19-
// +groupName=infrastructure.cluster.x-k8s.io
2017
package v1alpha6
2118

2219
import (

‎api/v1alpha6/openstackcluster_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,8 @@ type OpenStackClusterStatus struct {
212212
FailureMessage *string `json:"failureMessage,omitempty"`
213213
}
214214

215+
// +genclient
216+
// +genclient:Namespaced
215217
// +kubebuilder:object:root=true
216218
// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackCluster has been deprecated and will be removed in a future release of the API. Please upgrade."
217219
// +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc

‎api/v1alpha6/openstackclustertemplate_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ type OpenStackClusterTemplateSpec struct {
3030
Template OpenStackClusterTemplateResource `json:"template"`
3131
}
3232

33+
// +genclient
34+
// +genclient:Namespaced
3335
// +kubebuilder:object:root=true
3436
// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackClusterTemplate has been deprecated and will be removed in a future release of the API. Please upgrade."
3537
// +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct

‎api/v1alpha6/openstackmachine_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,8 @@ type OpenStackMachineStatus struct {
136136
Conditions clusterv1.Conditions `json:"conditions,omitempty"`
137137
}
138138

139+
// +genclient
140+
// +genclient:Namespaced
139141
// +kubebuilder:object:root=true
140142
// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackMachine has been deprecated and will be removed in a future release of the API. Please upgrade."
141143
// +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm

‎api/v1alpha6/openstackmachinetemplate_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ type OpenStackMachineTemplateSpec struct {
2525
Template OpenStackMachineTemplateResource `json:"template"`
2626
}
2727

28+
// +genclient
29+
// +genclient:Namespaced
2830
// +kubebuilder:object:root=true
2931
// +kubebuilder:deprecatedversion:warning="The v1alpha6 version of OpenStackMachineTemplate has been deprecated and will be removed in a future release of the API. Please upgrade."
3032
// +kubebuilder:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt

‎api/v1alpha7/doc.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,8 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17+
// Package v1alpha7 contains API Schema definitions for the infrastructure v1alpha7 API group.
18+
// +kubebuilder:object:generate=true
19+
// +groupName=infrastructure.cluster.x-k8s.io
1720
// +k8s:conversion-gen=sigs.k8s.io/cluster-api-provider-openstack/api/v1beta1
1821
package v1alpha7

‎api/v1alpha7/groupversion_info.go

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,6 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17-
// package v1alpha7 contains API Schema definitions for the infrastructure v1alpha7 API group
18-
// +kubebuilder:object:generate=true
19-
// +groupName=infrastructure.cluster.x-k8s.io
2017
package v1alpha7
2118

2219
import (

‎api/v1alpha7/openstackcluster_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,8 @@ type OpenStackClusterStatus struct {
229229
FailureMessage *string `json:"failureMessage,omitempty"`
230230
}
231231

232+
// +genclient
233+
// +genclient:Namespaced
232234
// +kubebuilder:object:root=true
233235
// +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
234236
// +kubebuilder:subresource:status

‎api/v1alpha7/openstackclustertemplate_types.go

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,10 @@ type OpenStackClusterTemplateSpec struct {
3030
Template OpenStackClusterTemplateResource `json:"template"`
3131
}
3232

33-
//+kubebuilder:object:root=true
34-
//+kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
33+
// +genclient
34+
// +genclient:Namespaced
35+
// +kubebuilder:object:root=true
36+
// +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
3537

3638
// OpenStackClusterTemplate is the Schema for the openstackclustertemplates API.
3739
type OpenStackClusterTemplate struct {

‎api/v1alpha7/openstackmachine_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,8 @@ type OpenStackMachineStatus struct {
136136
Conditions clusterv1.Conditions `json:"conditions,omitempty"`
137137
}
138138

139+
// +genclient
140+
// +genclient:Namespaced
139141
// +kubebuilder:object:root=true
140142
// +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm
141143
// +kubebuilder:subresource:status

‎api/v1alpha7/openstackmachinetemplate_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ type OpenStackMachineTemplateSpec struct {
2525
Template OpenStackMachineTemplateResource `json:"template"`
2626
}
2727

28+
// +genclient
29+
// +genclient:Namespaced
2830
// +kubebuilder:object:root=true
2931
// +kubebuilder:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt
3032

‎api/v1beta1/doc.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,7 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17+
// Package v1beta1 contains API Schema definitions for the infrastructure v1beta1 API group.
18+
// +kubebuilder:object:generate=true
19+
// +groupName=infrastructure.cluster.x-k8s.io
1720
package v1beta1

‎api/v1beta1/openstackcluster_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,8 @@ type OpenStackClusterStatus struct {
235235
FailureMessage *string `json:"failureMessage,omitempty"`
236236
}
237237

238+
// +genclient
239+
// +genclient:Namespaced
238240
// +kubebuilder:object:root=true
239241
// +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
240242
// +kubebuilder:storageversion

‎api/v1beta1/openstackclustertemplate_types.go

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,11 @@ type OpenStackClusterTemplateSpec struct {
3030
Template OpenStackClusterTemplateResource `json:"template"`
3131
}
3232

33-
//+kubebuilder:object:root=true
33+
// +genclient
34+
// +genclient:Namespaced
35+
// +kubebuilder:object:root=true
3436
// +kubebuilder:storageversion
35-
//+kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
37+
// +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
3638

3739
// OpenStackClusterTemplate is the Schema for the openstackclustertemplates API.
3840
type OpenStackClusterTemplate struct {

‎api/v1beta1/openstackmachine_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,8 @@ type OpenStackMachineStatus struct {
146146
Conditions clusterv1.Conditions `json:"conditions,omitempty"`
147147
}
148148

149+
// +genclient
150+
// +genclient:Namespaced
149151
// +kubebuilder:object:root=true
150152
// +kubebuilder:storageversion
151153
// +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm

‎api/v1beta1/openstackmachinetemplate_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ type OpenStackMachineTemplateSpec struct {
2525
Template OpenStackMachineTemplateResource `json:"template"`
2626
}
2727

28+
// +genclient
29+
// +genclient:Namespaced
2830
// +kubebuilder:object:root=true
2931
// +kubebuilder:storageversion
3032
// +kubebuilder:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt

‎docs/book/gen-crd-api-reference-docs/config.json

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{
2+
"hideMemberFields": [
3+
"TypeMeta"
4+
],
5+
"hideTypePatterns": [
6+
"ParseError$",
7+
"List$"
8+
],
9+
"externalPackages": [
10+
{
11+
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
12+
"docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
13+
},
14+
{
15+
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Condition$",
16+
"docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition"
17+
},
18+
{
19+
"typeMatchPrefix": "^sigs\\.k8s\\.io/cluster-api/api/v1beta1",
20+
"docsURLTemplate": "https://doc.crds.dev/github.com/kubernetes-sigs/[email protected]"
21+
},
22+
{
23+
"typeMatchPrefix": "^sigs\\.k8s\\.io/cluster-api/api/v1beta1",
24+
"docsURLTemplate": "https://doc.crds.dev/github.com/kubernetes-sigs/[email protected]"
25+
},
26+
{
27+
"typeMatchPrefix": "^sigs\\.k8s\\.io/cluster-api/errors",
28+
"docsURLTemplate": "https://pkg.go.dev/sigs.k8s.io/[email protected]/errors#{{.TypeIdentifier}}"
29+
}
30+
],
31+
"typeDisplayNamePrefixOverrides": {
32+
"k8s.io/api/": "Kubernetes ",
33+
"k8s.io/apimachinery/pkg/apis/": "Kubernetes "
34+
},
35+
"markdownDisabled": false
36+
}

‎docs/book/gen-crd-api-reference-docs/template/members.tpl

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{{ define "members" }}
2+
3+
{{ range .Members }}
4+
{{ if not (hiddenMember .)}}
5+
<tr>
6+
<td>
7+
<code>{{ fieldName . }}</code><br/>
8+
<em>
9+
{{ if linkForType .Type }}
10+
<a href="{{ linkForType .Type}}">
11+
{{ typeDisplayName .Type }}
12+
</a>
13+
{{ else }}
14+
{{ typeDisplayName .Type }}
15+
{{ end }}
16+
</em>
17+
</td>
18+
<td>
19+
{{ if fieldEmbedded . }}
20+
<p>
21+
(Members of <code>{{ fieldName . }}</code> are embedded into this type.)
22+
</p>
23+
{{ end}}
24+
25+
{{ if isOptionalMember .}}
26+
<em>(Optional)</em>
27+
{{ end }}
28+
29+
{{ safe (renderComments .CommentLines) }}
30+
31+
{{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
32+
Refer to the Kubernetes API documentation for the fields of the
33+
<code>metadata</code> field.
34+
{{ end }}
35+
36+
{{ if or (eq (fieldName .) "spec") }}
37+
<br/>
38+
<br/>
39+
<table>
40+
{{ template "members" .Type }}
41+
</table>
42+
{{ end }}
43+
</td>
44+
</tr>
45+
{{ end }}
46+
{{ end }}
47+
48+
{{ end }}

‎docs/book/gen-crd-api-reference-docs/template/pkg.tpl

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{{ define "packages" }}
2+
3+
{{ range .packages }}
4+
<h2 id="{{- packageAnchorID . -}}">
5+
{{- packageDisplayName . -}}
6+
</h2>
7+
8+
{{ with (index .GoPackages 0 )}}
9+
{{ with .DocComments }}
10+
<p>
11+
{{ safe (renderComments .) }}
12+
</p>
13+
{{ end }}
14+
{{ end }}
15+
16+
Resource Types:
17+
<ul>
18+
{{- range (visibleTypes (sortedTypes .Types)) -}}
19+
{{ if isExportedType . -}}
20+
<li>
21+
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
22+
</li>
23+
{{- end }}
24+
{{- end -}}
25+
</ul>
26+
27+
{{ range (visibleTypes (sortedTypes .Types))}}
28+
{{ template "type" . }}
29+
{{ end }}
30+
<hr/>
31+
{{ end }}
32+
33+
<p><em>
34+
Generated with <code>gen-crd-api-reference-docs</code>.
35+
</em></p>
36+
37+
{{ end }}

0 commit comments

Comments
 (0)