Skip to content

Commit 64fe18e

Browse files
adambkaplanadambkaplan
committed
feat: Generate 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. Signed-off-by: Adam Kaplan <[email protected]>
1 parent cbc78b7 commit 64fe18e

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 ?= "v0.14.0"
52+
53+
.PHONY: gen-api-docs
54+
gen-api-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)