Skip to content

Commit 550afae

Browse files
adambkaplanadambkaplan
committed
feat: Generate Build API Reference Docs
Auto-generate API reference docs from Go comments. This is considered best practice. - Utilize elastic/crd-ref-docs tool. This is much easier to use than the Kubernetes CRD docs stack. - Copy markdown templates from elastic/crd-ref-docs, so they can be customized later. - Use Makefile to run script generating docs from Shipwright build project. The main branch is used to generate the docs for now, since it contains the necessary kubebuilder markers to generate useful reference material. In the future, we can pin this to a release tag. Signed-off-by: Adam Kaplan <[email protected]>
1 parent cbc78b7 commit 550afae

File tree

11 files changed

+1386
-1
lines changed

11 files changed

+1386
-1
lines changed

‎.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,11 @@ resources/
66
public/
77
.hugo_build.lock
88

9+
# Supporting tools
10+
bin/
11+
12+
# API Generation
13+
api-gen/build/
14+
915
# IDEs
1016
.vscode

‎Makefile

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,19 @@ serve: ## serve the content locally for testing
3737

3838
.PHONY: serve-preview
3939
serve-preview: ## serve the preview content locally for testing
40-
hugo -t docsy server -F
40+
hugo -t docsy server -F
41+
42+
.PHONY: bin-dir
43+
bin-dir: ## Creates a local "bin" directory for helper applications.
44+
@mkdir ./bin || true
45+
46+
.PHONY: crd-ref-docs
47+
crd-ref-docs: bin-dir ## install crd-ref-docs tool
48+
GOBIN=$(shell pwd)/bin go install github.com/elastic/[email protected]
49+
50+
BUILD_REPO ?= "https://github.com/shipwright-io/build.git"
51+
BUILD_VERSION ?= "main"
52+
53+
.PHONY: gen-api-docs
54+
gen-api-docs: crd-ref-docs ## generate API reference documentation
55+
BUILD_REPO=$(BUILD_REPO) BUILD_VERSION=$(BUILD_VERSION) ./hack/gen-api-docs.sh

‎api-gen/build.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
processor:
2+
ignoreFields:
3+
- "TypeMeta$"
4+
render:
5+
kubernetesVersion: 1.30

‎api-gen/templates/markdown/gv_details.tpl

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{{- define "gvDetails" -}}
2+
{{- $gv := . -}}
3+
4+
# {{ $gv.GroupVersionString }}
5+
6+
{{ $gv.Doc }}
7+
8+
{{- if len $gv.Kinds }}
9+
## Resource Types
10+
{{- range $gv.SortedKinds }}
11+
- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
12+
{{- end }}
13+
{{ end }}
14+
15+
{{ range $gv.SortedTypes }}
16+
{{ template "type" . }}
17+
{{ end }}
18+
19+
{{- end -}}

‎api-gen/templates/markdown/gv_list.tpl

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{{- define "gvList" -}}
2+
{{- $groupVersions := . -}}
3+
4+
---
5+
title: {{env "API_GROUP"}} Resources
6+
weight: {{env "API_WEIGHT"}}
7+
---
8+
9+
# Packages
10+
{{- range $groupVersions }}
11+
- {{ markdownRenderGVLink . }}
12+
{{- end }}
13+
14+
{{ range $groupVersions }}
15+
{{ template "gvDetails" . }}
16+
{{ end }}
17+
18+
{{- end -}}

‎api-gen/templates/markdown/type.tpl

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{{- define "type" -}}
2+
{{- $type := . -}}
3+
{{- if markdownShouldRenderType $type -}}
4+
5+
### {{ $type.Name }}
6+
7+
{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }}
8+
9+
{{ $type.Doc }}
10+
11+
{{ if $type.Validation -}}
12+
_Validation:_
13+
{{- range $type.Validation }}
14+
- {{ . }}
15+
{{- end }}
16+
{{- end }}
17+
18+
{{ if $type.References -}}
19+
_Appears in:_
20+
{{- range $type.SortedReferences }}
21+
- {{ markdownRenderTypeLink . }}
22+
{{- end }}
23+
{{- end }}
24+
25+
{{ if $type.Members -}}
26+
| Field | Description | Default | Validation |
27+
| --- | --- | --- | --- |
28+
{{ if $type.GVK -}}
29+
| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | | |
30+
| `kind` _string_ | `{{ $type.GVK.Kind }}` | | |
31+
{{ end -}}
32+
33+
{{ range $type.Members -}}
34+
| `{{ .Name }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
35+
{{ end -}}
36+
37+
{{ end -}}
38+
39+
{{ if $type.EnumValues -}}
40+
| Field | Description |
41+
| --- | --- |
42+
{{ range $type.EnumValues -}}
43+
| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
44+
{{ end -}}
45+
{{ end -}}
46+
47+
48+
{{- end -}}
49+
{{- end -}}

‎api-gen/templates/markdown/type_members.tpl

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{{- define "type_members" -}}
2+
{{- $field := . -}}
3+
{{- if eq $field.Name "metadata" -}}
4+
Refer to Kubernetes API documentation for fields of `metadata`.
5+
{{- else -}}
6+
{{ markdownRenderFieldDoc $field.Doc }}
7+
{{- end -}}
8+
{{- end -}}

‎content/en/docs/ref/_index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Reference"
3+
weight: 30
4+
---
5+
6+
This section contains reference documentation.

‎content/en/docs/ref/api/_index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: API Reference
3+
weight: 10
4+
---

0 commit comments

Comments
 (0)