Skip to content

Commit a036d00

Browse files
squaremosquaremo
committed
Add target for API docs generation to Makefile
This adapts the API docs generation, minimally, from kustomize-controller to work here. Signed-off-by: Michael Bridgen <[email protected]>
1 parent fdafff5 commit a036d00

File tree

6 files changed

+230
-0
lines changed

6 files changed

+230
-0
lines changed

‎Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ dev-deploy: manifests
7070
manifests: controller-gen
7171
cd api; $(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role paths="./..." output:crd:artifacts:config="../config/crd/bases"
7272

73+
# Generate API reference documentation
74+
api-docs: gen-crd-api-reference-docs
75+
$(API_REF_GEN) -api-dir=./api/v1alpha1 -config=./hack/api-docs/config.json -template-dir=./hack/api-docs/template -out-file=./docs/api/image-automation.md
76+
7377
# Run go fmt against code
7478
fmt:
7579
go fmt ./...
@@ -108,3 +112,19 @@ CONTROLLER_GEN=$(GOBIN)/controller-gen
108112
else
109113
CONTROLLER_GEN=$(shell which controller-gen)
110114
endif
115+
116+
# Find or download gen-crd-api-reference-docs
117+
gen-crd-api-reference-docs:
118+
ifeq (, $(shell which gen-crd-api-reference-docs))
119+
@{ \
120+
set -e ;\
121+
API_REF_GEN_TMP_DIR=$$(mktemp -d) ;\
122+
cd $$API_REF_GEN_TMP_DIR ;\
123+
go mod init tmp ;\
124+
go get github.com/ahmetb/[email protected] ;\
125+
rm -rf $$API_REF_GEN_TMP_DIR ;\
126+
}
127+
API_REF_GEN=$(GOBIN)/gen-crd-api-reference-docs
128+
else
129+
API_REF_GEN=$(shell which gen-crd-api-reference-docs)
130+
endif

‎api/v1alpha1/doc.go‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/*
2+
Copyright 2020 The Flux authors
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Package v1alpha contains API types for the image v1alpha1 API
18+
// group. The types here are concerned with automated updates to git,
19+
// based on metadata from OCI image registries gathered by the
20+
// image-reflector-controller.
21+
//
22+
// +kubebuilder:object:generate=true
23+
// +groupName=image.toolkit.fluxcd.io
24+
package v1alpha1

‎hack/api-docs/config.json‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
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://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
13+
},
14+
{
15+
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
16+
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
17+
},
18+
{
19+
"typeMatchPrefix": "^github.com/fluxcd/pkg/runtime/dependency\\.CrossNamespaceDependencyReference$",
20+
"docsURLTemplate": "https://godoc.org/github.com/fluxcd/pkg/runtime/dependency#CrossNamespaceDependencyReference"
21+
},
22+
{
23+
"typeMatchPrefix": "^github.com/fluxcd/pkg/apis/meta",
24+
"docsURLTemplate": "https://godoc.org/github.com/fluxcd/pkg/apis/meta#{{ .TypeIdentifier }}"
25+
}
26+
],
27+
"typeDisplayNamePrefixOverrides": {
28+
"k8s.io/api/": "Kubernetes ",
29+
"k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
30+
"github.com/fluxcd/pkg/runtime/": "Runtime ",
31+
"github.com/fluxcd/pkg/apis/meta/": "Meta "
32+
},
33+
"markdownDisabled": false
34+
}

‎hack/api-docs/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-docs/template/pkg.tpl‎

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

‎hack/api-docs/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 }}

0 commit comments

Comments
 (0)