Merge pull request #611 from googs1025/add_api_reference

docs: add JobSet API reference

Makefile

@@ -133,7 +133,7 @@ test-python-sdk:
 	./hack/python-sdk/test-sdk.sh
 
 .PHONY: verify
-verify: vet fmt-verify ci-lint manifests generate toc-verify
+verify: vet fmt-verify ci-lint manifests generate toc-verify generate-apiref
 	git --no-pager diff --exit-code config api client-go
 
 
@@ -294,4 +294,14 @@ golangci-lint: ## Download golangci-lint locally if necessary.
 GOTESTSUM = $(shell pwd)/bin/gotestsum
 .PHONY: gotestsum
 gotestsum: ## Download gotestsum locally if necessary.
-	@GOBIN=$(PROJECT_DIR)/bin GO111MODULE=on $(GO_CMD) install gotest.tools/gotestsum@v1.8.2
+	@GOBIN=$(PROJECT_DIR)/bin GO111MODULE=on $(GO_CMD) install gotest.tools/gotestsum@v1.8.2
+
+
+.PHONY: generate-apiref
+generate-apiref: genref
+	cd $(PROJECT_DIR)/hack/genref/ && $(GENREF) -o $(PROJECT_DIR)/site/content/en/docs/reference
+
+GENREF = $(PROJECT_DIR)/bin/genref
+.PHONY: genref
+genref: ## Download genref locally if necessary.
+	@GOBIN=$(PROJECT_DIR)/bin $(GO_CMD) install github.com/kubernetes-sigs/reference-docs/genref@v0.28.0

hack/genref/config.yaml

@@ -0,0 +1,20 @@
+# more details can be found  https://github.com/kubernetes-sigs/reference-docs/tree/master/genref
+hiddenMemberFields:
+  - "TypeMeta"
+  - "ObjectMeta"
+
+apis:
+  - name: jobset
+    title: JobSet API
+    package: sigs.k8s.io/jobset
+    path: api/jobset/v1alpha2
+
+externalPackages:
+  - match: ^k8s\.io/(api|apimachinery/pkg/apis)/
+    target: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#{{- lower .TypeIdentifier -}}-{{- arrIndex .PackageSegments -1 -}}-{{- arrIndex .PackageSegments -2 -}}
+  - match: ^k8s\.io/apimachinery/pkg/api/resource\.Quantity$
+    target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity
+  - match: ^k8s.io/component-base/config/v1alpha1.
+    target: https://pkg.go.dev/k8s.io/component-base/config/v1alpha1#{{- .TypeIdentifier -}}
+  - match: ^time\.Duration$
+    target: https://pkg.go.dev/time#Duration

hack/genref/markdown/members.tpl

@@ -0,0 +1,34 @@
+{{ define "members" }}
+  {{/* . is a apiType */}}
+  {{- range .GetMembers -}}
+    {{/* . is a apiMember */}}
+    {{- if not .Hidden }}
+<tr><td><code>{{ .FieldName }}</code>
+      {{- if not .IsOptional }} <B>[Required]</B>{{- end -}}
+<br/>
+{{/* Link for type reference */}}
+      {{- with .GetType -}}
+        {{- if .Link -}}
+<a href="{{ .Link }}"><code>{{ .DisplayName }}</code></a>
+        {{- else -}}
+<code>{{ .DisplayName }}</code>
+        {{- end -}}
+      {{- end }}
+</td>
+<td>
+   {{- if .IsInline -}}
+(Members of <code>{{ .FieldName }}</code> are embedded into this type.)
+   {{- end }}
+   {{ if .GetComment -}}
+   {{ .GetComment }}
+   {{- else -}}
+   <span class="text-muted">No description provided.</span>
+   {{- end }}
+   {{- if and (eq (.GetType.Name.Name) "ObjectMeta") -}}
+Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.
+   {{- end -}}
+</td>
+</tr>
+    {{- end }}
+  {{- end }}
+{{ end }}

hack/genref/markdown/pkg.tpl

@@ -0,0 +1,46 @@
+{{ define "packages" -}}
+
+{{- range $idx, $val := .packages -}}
+{{/* Special handling for config */}}
+  {{- if .IsMain -}}
+---
+title: {{ .Title }}
+content_type: tool-reference
+package: {{ .DisplayName }}
+auto_generated: true
+description: Generated API reference documentation for {{ .DisplayName }}.
+---
+{{ .GetComment -}}
+  {{- end -}}
+{{- end }}
+
+## Resource Types 
+
+{{ range .packages -}}
+  {{ $isConfig := (eq .GroupName "") }}
+  {{- range .VisibleTypes -}}
+    {{- if or .IsExported (and $isConfig (eq .DisplayName "Configuration")) }}
+- [{{ .DisplayName }}]({{ .Link }})
+    {{- end -}}
+  {{- end -}}
+{{- end -}}
+
+{{ range .packages }}
+  {{ if ne .GroupName "" -}}
+    {{/* For package with a group name, list all type definitions in it. */}}
+    {{- range .VisibleTypes }}
+      {{- if or .Referenced .IsExported -}}
+{{ template "type" . }}
+      {{- end -}}
+    {{ end }}
+  {{ else }}
+    {{/* For package w/o group name, list only types referenced. */}}
+    {{ $isConfig := (eq .GroupName "") }}
+    {{- range .VisibleTypes -}}
+      {{- if or .Referenced $isConfig -}}
+{{ template "type" . }}
+      {{- end -}}
+    {{- end }}
+  {{- end }}
+{{- end }}
+{{- end }}

hack/genref/markdown/type.tpl

@@ -0,0 +1,37 @@
+{{ define "type" }}
+
+## `{{ .Name.Name }}`     {#{{ .Anchor }}}
+
+{{ if eq .Kind "Alias" -}}
+(Alias of `{{ .Underlying }}`)
+{{ end }}
+
+{{- with .References }}
+**Appears in:**
+{{ range . }}
+{{ if or .Referenced .IsExported -}}
+- [{{ .DisplayName }}]({{ .Link }})
+{{ end -}}
+{{- end -}}
+{{- end }}
+
+{{ if .GetComment -}}
+{{ .GetComment }}
+{{ end }}
+{{ if .GetMembers -}}
+<table class="table">
+<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
+<tbody>
+    {{/* . is a apiType */}}
+    {{- if .IsExported -}}
+{{/* Add apiVersion and kind rows if deemed necessary */}}
+<tr><td><code>apiVersion</code><br/>string</td><td><code>{{- .APIGroup -}}</code></td></tr>
+<tr><td><code>kind</code><br/>string</td><td><code>{{- .Name.Name -}}</code></td></tr>
+    {{ end -}}
+
+{{/* The actual list of members is in the following template */}}
+{{- template "members" . -}}
+</tbody>
+</table>
+{{- end -}}
+{{- end -}}