Skip to content

Commit 3066a8c

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

33 files changed

+13388
-14
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 & 0 deletions
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
@@ -248,6 +249,7 @@ modules: ## Runs go mod to ensure proper vendoring.
248249
generate: ## Generate code
249250
$(MAKE) generate-go
250251
$(MAKE) generate-manifests
252+
$(MAKE) generate-api-docs
251253

252254
.PHONY: generate-go
253255
generate-go: $(MOCKGEN)
@@ -279,6 +281,24 @@ generate-manifests: $(CONTROLLER_GEN) ## Generate manifests e.g. CRD, RBAC etc.
279281
output:rbac:dir=$(RBAC_ROOT) \
280282
rbac:roleName=manager-role
281283

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

‎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/v1alpha8
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:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
217219
// +kubebuilder:subresource:status

‎api/v1alpha6/openstackclustertemplate_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ type OpenStackClusterTemplate struct {
4141
Spec OpenStackClusterTemplateSpec `json:"spec,omitempty"`
4242
}
4343

44+
// +genclient
45+
// +genclient:Namespaced
4446
//+kubebuilder:object:root=true
4547

4648
// OpenStackClusterTemplateList contains a list of OpenStackClusterTemplate.

‎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:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm
141143
// +kubebuilder:subresource:status

‎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:resource:path=openstackmachinetemplates,scope=Namespaced,categories=cluster-api,shortName=osmt
3032

‎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/v1alpha8
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: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,11 @@ 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:storageversion
37+
// +kubebuilder:resource:path=openstackclustertemplates,scope=Namespaced,categories=cluster-api,shortName=osct
3538

3639
// OpenStackClusterTemplate is the Schema for the openstackclustertemplates API.
3740
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
@@ -36,6 +36,8 @@ type OpenStackMachineTemplate struct {
3636
Spec OpenStackMachineTemplateSpec `json:"spec,omitempty"`
3737
}
3838

39+
// +genclient
40+
// +genclient:Namespaced
3941
// +kubebuilder:object:root=true
4042

4143
// OpenStackMachineTemplateList contains a list of OpenStackMachineTemplate.

‎api/v1alpha8/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 v1alpha8 contains API Schema definitions for the infrastructure v1alpha8 API group
18+
// +kubebuilder:object:generate=true
19+
// +groupName=infrastructure.cluster.x-k8s.io
1720
package v1alpha8

‎api/v1alpha8/groupversion_info.go

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,6 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1313
See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
16-
17-
// package v1alpha8 contains API Schema definitions for the infrastructure v1alpha8 API group
18-
// +kubebuilder:object:generate=true
19-
// +groupName=infrastructure.cluster.x-k8s.io
2016
package v1alpha8
2117

2218
import (

‎api/v1alpha8/openstackcluster_types.go

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

245+
// +genclient
246+
// +genclient:Namespaced
245247
// +kubebuilder:object:root=true
246248
// +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
247249
// +kubebuilder:storageversion

‎api/v1alpha8/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/v1alpha8/openstackmachine_types.go

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

146+
// +genclient
147+
// +genclient:Namespaced
146148
// +kubebuilder:object:root=true
147149
// +kubebuilder:storageversion
148150
// +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm

‎api/v1alpha8/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)