Skip to content

Commit e52e07d

Browse files
mquhuymquhuy
committed
Generate reference documentation automatically from godocs in the API
1 parent c73d55d commit e52e07d

File tree

8 files changed

+204
-3
lines changed

8 files changed

+204
-3
lines changed

‎api/v1alpha5/doc.go

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,10 @@ distributed under the License is distributed on an "AS IS" BASIS,
1212
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.
15+
16+
Package v1alpha5 contains API Schema definitions for the v1alpha5 API group
17+
+kubebuilder:object:generate=true
18+
+groupName=infrastructure.cluster.x-k8s.io
1519
*/
1620

17-
// +k8s:conversion-gen=sigs.k8s.io/cluster-api-provider-openstack/api/v1alpha7
1821
package v1alpha5

‎api/v1alpha6/doc.go

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,10 @@ distributed under the License is distributed on an "AS IS" BASIS,
1212
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.
15+
16+
Package v1alpha6 contains API Schema definitions for the v1alpha6 API group
17+
+kubebuilder:object:generate=true
18+
+groupName=infrastructure.cluster.x-k8s.io
1519
*/
1620

17-
// +k8s:conversion-gen=sigs.k8s.io/cluster-api-provider-openstack/api/v1alpha7
1821
package v1alpha6

‎api/v1alpha7/doc.go

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ distributed under the License is distributed on an "AS IS" BASIS,
1212
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.
15+
16+
Package v1alpha7 contains API Schema definitions for the v1alpha7 API group
17+
+kubebuilder:object:generate=true
18+
+groupName=infrastructure.cluster.x-k8s.io
1519
*/
1620

1721
package v1alpha7

‎docs/book/Makefile

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,11 @@ verify: generate ## Verify that dependent artifacts are up to date
3838
fi
3939

4040
.PHONY: build
41-
build: $(BOOK_SRCS) $(MDBOOK) $(MDBOOK_EMBED) $(MDBOOK_RELEASELINK) $(MDBOOK_TABULATE) ## Build the book
41+
build: $(BOOK_SRCS) $(MDBOOK) $(MDBOOK_EMBED) $(MDBOOK_RELEASELINK) $(MDBOOK_TABULATE)
42+
../../hack/generate-api-docs.sh
4243
$(MDBOOK) build
44+
rm -rf src/api src/SUMMARY.md
45+
mv src/SUMMARY_ORIGINAL.md src/SUMMARY.md
4346

4447
.PHONY: serve
4548
serve: $(MDBOOK) $(MDBOOK_EMBED) $(MDBOOK_RELEASELINK) $(MDBOOK_TABULATE) ## Run a local webserver with the compiled book

‎hack/api/template/members.tpl

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

‎hack/api/template/pkg.tpl

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{{ define "packages" }}
2+
<h1>API reference</h1>
3+
4+
{{ range .packages }}
5+
{{ with (index .GoPackages 0 )}}
6+
{{ with .DocComments }}
7+
{{ safe (renderComments .) }}
8+
{{ end }}
9+
{{ end }}
10+
11+
Resource Types:
12+
13+
<ul class="simple">
14+
{{- range (visibleTypes (sortedTypes .Types)) -}}
15+
{{ if isExportedType . -}}
16+
<li>
17+
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
18+
</li>
19+
{{- end }}
20+
{{- end -}}
21+
</ul>
22+
23+
{{ range (visibleTypes (sortedTypes .Types))}}
24+
{{ template "type" . }}
25+
{{ end }}
26+
{{ end }}
27+
28+
<div class="admonition note">
29+
<p class="last">This page was automatically generated with <code>gen-crd-api-reference-docs</code></p>
30+
</div>
31+
{{ end }}

‎hack/api/template/type.tpl

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{{ define "type" }}
2+
<h3 id="{{ anchorIDForType . }}">
3+
{{- .Name.Name }}
4+
{{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias){{ end -}}
5+
</h3>
6+
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+
{{ with .CommentLines }}
21+
{{ safe (renderComments .) }}
22+
{{ end }}
23+
24+
{{ if .Members }}
25+
<div class="md-typeset__scrollwrap">
26+
<div class="md-typeset__table">
27+
<table>
28+
<thead>
29+
<tr>
30+
<th>Field</th>
31+
<th>Description</th>
32+
</tr>
33+
</thead>
34+
<tbody>
35+
{{ if isExportedType . }}
36+
<tr>
37+
<td>
38+
<code>apiVersion</code><br>
39+
string</td>
40+
<td>
41+
<code>{{ apiGroup . }}</code>
42+
</td>
43+
</tr>
44+
<tr>
45+
<td>
46+
<code>kind</code><br>
47+
string
48+
</td>
49+
<td>
50+
<code>{{ .Name.Name }}</code>
51+
</td>
52+
</tr>
53+
{{ end }}
54+
{{ template "members" . }}
55+
</tbody>
56+
</table>
57+
</div>
58+
</div>
59+
{{ end }}
60+
{{ end }}

‎hack/generate-api-docs.sh

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
#!/usr/bin/env bash
2+
3+
# Copyright 2023 The Kubernetes Authors.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -o errexit
18+
set -o nounset
19+
set -o pipefail
20+
21+
__dir__=$(realpath $(dirname $0))
22+
source "${__dir__}/ensure-go.sh"
23+
verify_go_version
24+
25+
go install github.com/ahmetb/gen-crd-api-reference-docs@latest
26+
27+
__root__=$(realpath "${__dir__}/..")
28+
API_VERSIONS=($(ls "${__root__}/api"))
29+
30+
BOOK_DIR="${__root__}/docs/book"
31+
32+
SUMMARY_FILE="${BOOK_DIR}/src/SUMMARY.md"
33+
API_DOC_DIR="${BOOK_DIR}/src/api"
34+
35+
ORIGINAL_SUMMARY_FILE="${BOOK_DIR}/src/SUMMARY_ORIGINAL.md"
36+
37+
cp "${SUMMARY_FILE}" "${ORIGINAL_SUMMARY_FILE}"
38+
39+
mkdir -p "${API_DOC_DIR}"
40+
41+
cd "${__root__}"
42+
echo "- [Reference](./api/index.md)" >> "${SUMMARY_FILE}"
43+
touch "${API_DOC_DIR}/index.md"
44+
45+
for api_version in "${API_VERSIONS[@]}"; do
46+
gen-crd-api-reference-docs --api-dir="./api/${api_version}" --config=./hack/api/config.json --template-dir=./hack/api/template -out-file="${API_DOC_DIR}/${api_version}.md"
47+
echo " - [${api_version}](./api/${api_version}.md)" >> "${SUMMARY_FILE}"
48+
done
49+
50+
# rm -f "${SUMMARY_FILE}"
51+
# mv "${ORIGINAL_SUMMARY_FILE}" "${SUMMARY_FILE}"

0 commit comments

Comments
 (0)