Skip to content

Commit 40b025d

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

26 files changed

+8524
-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: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,13 @@ 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
56+
57+
# Setup-envtest
58+
SETUP_ENVTEST_VER := v0.0.0-20221201045826-d9912251cd81
59+
SETUP_ENVTEST_BIN := setup-envtest
60+
SETUP_ENVTEST := $(abspath $(TOOLS_BIN_DIR)/$(SETUP_ENVTEST_BIN)-$(SETUP_ENVTEST_VER))
61+
SETUP_ENVTEST_PKG := sigs.k8s.io/controller-runtime/tools/setup-envtest
5562

5663
# Kubebuilder
5764
export KUBEBUILDER_ENVTEST_KUBERNETES_VERSION ?= 1.25.0
@@ -257,6 +264,7 @@ modules: ## Runs go mod to ensure proper vendoring.
257264
generate: ## Generate code
258265
$(MAKE) generate-go
259266
$(MAKE) generate-manifests
267+
$(MAKE) generate-api-docs
260268

261269
.PHONY: generate-go
262270
generate-go: $(MOCKGEN)
@@ -285,6 +293,19 @@ generate-manifests: $(CONTROLLER_GEN) ## Generate manifests e.g. CRD, RBAC etc.
285293
output:rbac:dir=$(RBAC_ROOT) \
286294
rbac:roleName=manager-role
287295

296+
.PHONY: generate-api-docs
297+
generate-api-docs: $(GEN_CRD_API_REFERENCE_DOCS) ## Generate api documentation
298+
$(GEN_CRD_API_REFERENCE_DOCS) \
299+
-api-dir=./api/v1alpha7 \
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/v1alpha7/api.md
303+
$(GEN_CRD_API_REFERENCE_DOCS) \
304+
-api-dir=./api/v1alpha6 \
305+
-config=./docs/book/gen-crd-api-reference-docs/config.json \
306+
-template-dir=./docs/book/gen-crd-api-reference-docs/template \
307+
-out-file=./docs/book/src/api/v1alpha6/api.md
308+
288309
## --------------------------------------
289310
##@ Docker
290311
## --------------------------------------

‎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/v1alpha7
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,4 +14,7 @@ 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
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
@@ -222,6 +222,8 @@ type OpenStackClusterStatus struct {
222222
FailureMessage *string `json:"failureMessage,omitempty"`
223223
}
224224

225+
// +genclient
226+
// +genclient:Namespaced
225227
// +kubebuilder:object:root=true
226228
// +kubebuilder:resource:path=openstackclusters,scope=Namespaced,categories=cluster-api,shortName=osc
227229
// +kubebuilder:storageversion

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

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

137+
// +genclient
138+
// +genclient:Namespaced
137139
// +kubebuilder:object:root=true
138140
// +kubebuilder:storageversion
139141
// +kubebuilder:resource:path=openstackmachines,scope=Namespaced,categories=cluster-api,shortName=osm

‎api/v1alpha7/openstackmachinetemplate_types.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ type OpenStackMachineTemplate struct {
3737
Spec OpenStackMachineTemplateSpec `json:"spec,omitempty"`
3838
}
3939

40+
// +genclient
41+
// +genclient:Namespaced
4042
// +kubebuilder:object:root=true
4143

4244
// OpenStackMachineTemplateList contains a list of OpenStackMachineTemplate.

‎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: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
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+
{{ with .gitCommit }} on git commit <code>{{ . }}</code>{{end}}.
36+
</em></p>
37+
38+
{{ end }}

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
{{ define "type" }}
2+
3+
<h3 id="{{ anchorIDForType . }}">
4+
{{- .Name.Name }}
5+
{{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
6+
</h3>
7+
{{ with (typeReferences .) }}
8+
<p>
9+
(<em>Appears on:</em>
10+
{{- $prev := "" -}}
11+
{{- range . -}}
12+
{{- if $prev -}}, {{ end -}}
13+
{{ $prev = . }}
14+
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
15+
{{- end -}}
16+
)
17+
</p>
18+
{{ end }}
19+
20+
<p>
21+
{{ safe (renderComments .CommentLines) }}
22+
</p>
23+
24+
{{ with (constantsOfType .) }}
25+
<table>
26+
<thead>
27+
<tr>
28+
<th>Value</th>
29+
<th>Description</th>
30+
</tr>
31+
</thead>
32+
<tbody>
33+
{{- range . -}}
34+
<tr>
35+
{{- /*
36+
renderComments implicitly creates a <p> element, so we
37+
add one to the display name as well to make the contents
38+
of the two cells align evenly.
39+
*/ -}}
40+
<td><p>{{ typeDisplayName . }}</p></td>
41+
<td>{{ safe (renderComments .CommentLines) }}</td>
42+
</tr>
43+
{{- end -}}
44+
</tbody>
45+
</table>
46+
{{ end }}
47+
48+
{{ if .Members }}
49+
<table>
50+
<thead>
51+
<tr>
52+
<th>Field</th>
53+
<th>Description</th>
54+
</tr>
55+
</thead>
56+
<tbody>
57+
{{ if isExportedType . }}
58+
<tr>
59+
<td>
60+
<code>apiVersion</code><br/>
61+
string</td>
62+
<td>
63+
<code>
64+
{{apiGroup .}}
65+
</code>
66+
</td>
67+
</tr>
68+
<tr>
69+
<td>
70+
<code>kind</code><br/>
71+
string
72+
</td>
73+
<td><code>{{.Name.Name}}</code></td>
74+
</tr>
75+
{{ end }}
76+
{{ template "members" .}}
77+
</tbody>
78+
</table>
79+
{{ end }}
80+
81+
{{ end }}

‎docs/book/src/SUMMARY.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,8 @@
1111
- [v1alpha4 to v1alpha5](./topics/crd-changes/v1alpha4-to-v1alpha5.md)
1212
- [v1alpha5 to v1alpha6](./topics/crd-changes/v1alpha5-to-v1alpha6.md)
1313
- [v1alpha6 to v1alpha7](./topics/crd-changes/v1alpha6-to-v1alpha7.md)
14+
- [API reference](./api/index.md)
15+
- [v1alpha6](./api/v1alpha6/api.md)
16+
- [v1alpha7](./api/v1alpha7/api.md)
1417
- [Development](./development/development.md)
1518
- [Hacking CI](./development/ci.md)

‎docs/book/src/api/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# API reference

0 commit comments

Comments
 (0)