Skip to content

Commit fc1b3e1

Browse files
dgrove-ossdgrove-oss
authored
regenerate apiref for web site (#347)
+ Cleaned up markdown templates to improve yaml formatting of generated apiref + Added generate-apiref to precommit checks to ensure it stays up-to-date + Generate update API refs and publish to website.
1 parent 1f9796c commit fc1b3e1

File tree

5 files changed

+117
-17
lines changed

5 files changed

+117
-17
lines changed

‎.pre-commit-config.yaml

+7-1
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,11 @@ repos:
1111
entry: make lint-fix
1212
language: system
1313
pass_filenames: false
14+
- id: generate-apiref
15+
name: generate-apiref
16+
entry: make generate-apiref
17+
language: system
18+
pass_filenames: false
1419
- repo: https://github.com/google/yamlfmt
1520
rev: v0.10.0
1621
hooks:
@@ -20,7 +25,8 @@ repos:
2025
rev: v4.5.0
2126
hooks:
2227
- id: trailing-whitespace
28+
exclude: site/_pages/appwrapper.v1beta2.md
2329
- id: end-of-file-fixer
24-
exclude: hack/boilerplate.go.txt
30+
exclude: hack/boilerplate.go.txt|site/_pages/appwrapper.v1beta2.md
2531
- id: mixed-line-ending
2632
args: ["--fix=lf"]

‎site/_pages/appwrapper.v1beta2.md

+102-3
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,22 @@
22
permalink: /api/workload.codeflare.dev/v1beta2/
33
title: AppWrapper API
44
classes: wide
5+
description: Generated API reference documentation for workload.codeflare.dev/v1beta2.
56
---
67

78

8-
Generated API reference documentation for <no value>.
9-
109
## Resource Types
1110

11+
- [AppWrapper](#workload-codeflare-dev-v1beta2-AppWrapper)
12+
- [AppWrapperComponent](#workload-codeflare-dev-v1beta2-AppWrapperComponent)
13+
- [AppWrapperComponentStatus](#workload-codeflare-dev-v1beta2-AppWrapperComponentStatus)
14+
- [AppWrapperCondition](#workload-codeflare-dev-v1beta2-AppWrapperCondition)
15+
- [AppWrapperList](#workload-codeflare-dev-v1beta2-AppWrapperList)
16+
- [AppWrapperPhase](#workload-codeflare-dev-v1beta2-AppWrapperPhase)
17+
- [AppWrapperPodSet](#workload-codeflare-dev-v1beta2-AppWrapperPodSet)
18+
- [AppWrapperPodSetInfo](#workload-codeflare-dev-v1beta2-AppWrapperPodSetInfo)
19+
- [AppWrapperSpec](#workload-codeflare-dev-v1beta2-AppWrapperSpec)
20+
- [AppWrapperStatus](#workload-codeflare-dev-v1beta2-AppWrapperStatus)
1221

1322

1423
## `AppWrapper` {#workload-codeflare-dev-v1beta2-AppWrapper}
@@ -69,7 +78,7 @@ arbitrary metadata about the Component to customize its treatment by the AppWrap
6978
<a href="#workload-codeflare-dev-v1beta2-AppWrapperPodSet"><code>[]AppWrapperPodSet</code></a>
7079
</td>
7180
<td>
72-
<p>PodSets contained in the Component</p>
81+
<p>DeclaredPodSets for the Component (optional for known PodCreating GVKs)</p>
7382
</td>
7483
</tr>
7584
<tr><td><code>podSetInfos</code><br/>
@@ -89,6 +98,64 @@ arbitrary metadata about the Component to customize its treatment by the AppWrap
8998
</tbody>
9099
</table>
91100

101+
## `AppWrapperComponentStatus` {#workload-codeflare-dev-v1beta2-AppWrapperComponentStatus}
102+
103+
104+
**Appears in:**
105+
106+
- [AppWrapperStatus](#workload-codeflare-dev-v1beta2-AppWrapperStatus)
107+
108+
109+
<p>AppWrapperComponentStatus tracks the status of a single managed Component</p>
110+
111+
112+
<table class="table">
113+
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
114+
<tbody>
115+
116+
117+
<tr><td><code>name</code> <B>[Required]</B><br/>
118+
<code>string</code>
119+
</td>
120+
<td>
121+
<p>Name is the name of the Component</p>
122+
</td>
123+
</tr>
124+
<tr><td><code>kind</code> <B>[Required]</B><br/>
125+
<code>string</code>
126+
</td>
127+
<td>
128+
<p>Kind is the Kind of the Component</p>
129+
</td>
130+
</tr>
131+
<tr><td><code>apiVersion</code> <B>[Required]</B><br/>
132+
<code>string</code>
133+
</td>
134+
<td>
135+
<p>APIVersion is the APIVersion of the Component</p>
136+
</td>
137+
</tr>
138+
<tr><td><code>podSets</code> <B>[Required]</B><br/>
139+
<a href="#workload-codeflare-dev-v1beta2-AppWrapperPodSet"><code>[]AppWrapperPodSet</code></a>
140+
</td>
141+
<td>
142+
<p>PodSets is the validated PodSets for the Component (either from AppWrapperComponent.DeclaredPodSets or inferred by the controller)</p>
143+
</td>
144+
</tr>
145+
<tr><td><code>conditions</code><br/>
146+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta"><code>[]k8s.io/apimachinery/pkg/apis/meta/v1.Condition</code></a>
147+
</td>
148+
<td>
149+
<p>Conditions hold the latest available observations of the Component's current state.</p>
150+
<p>The type of the condition could be:</p>
151+
<ul>
152+
<li>ResourcesDeployed: The component is deployed on the cluster</li>
153+
</ul>
154+
</td>
155+
</tr>
156+
</tbody>
157+
</table>
158+
92159
## `AppWrapperPhase` {#workload-codeflare-dev-v1beta2-AppWrapperPhase}
93160

94161
(Alias of `string`)
@@ -110,6 +177,8 @@ arbitrary metadata about the Component to customize its treatment by the AppWrap
110177

111178
- [AppWrapperComponent](#workload-codeflare-dev-v1beta2-AppWrapperComponent)
112179

180+
- [AppWrapperComponentStatus](#workload-codeflare-dev-v1beta2-AppWrapperComponentStatus)
181+
113182

114183
<p>AppWrapperPodSet describes an homogeneous set of pods</p>
115184

@@ -133,6 +202,14 @@ arbitrary metadata about the Component to customize its treatment by the AppWrap
133202
<p>Path is the path Component.Template to the PodTemplateSpec for this PodSet</p>
134203
</td>
135204
</tr>
205+
<tr><td><code>annotations</code><br/>
206+
<code>map[string]string</code>
207+
</td>
208+
<td>
209+
<p>Annotations is an unstructured key value map that may be used to store and retrieve
210+
arbitrary metadata about the PodSet to customize its treatment by the AppWrapper controller.</p>
211+
</td>
212+
</tr>
136213
</tbody>
137214
</table>
138215

@@ -180,6 +257,13 @@ arbitrary metadata about the Component to customize its treatment by the AppWrap
180257
<p>Tolerations to be added to the PodSpecTemplate</p>
181258
</td>
182259
</tr>
260+
<tr><td><code>schedulingGates</code><br/>
261+
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podschedulinggate-v1-core"><code>[]k8s.io/api/core/v1.PodSchedulingGate</code></a>
262+
</td>
263+
<td>
264+
<p>SchedulingGates to be added to the PodSpecTemplate</p>
265+
</td>
266+
</tr>
183267
</tbody>
184268
</table>
185269

@@ -213,6 +297,13 @@ arbitrary metadata about the Component to customize its treatment by the AppWrap
213297
<p>Suspend suspends the AppWrapper when set to true</p>
214298
</td>
215299
</tr>
300+
<tr><td><code>managedBy</code> <B>[Required]</B><br/>
301+
<code>string</code>
302+
</td>
303+
<td>
304+
<p>ManagedBy is used to indicate the controller or entity that manages the AppWrapper.</p>
305+
</td>
306+
</tr>
216307
</tbody>
217308
</table>
218309

@@ -261,5 +352,13 @@ arbitrary metadata about the Component to customize its treatment by the AppWrap
261352
</ul>
262353
</td>
263354
</tr>
355+
<tr><td><code>componentStatus</code> <B>[Required]</B><br/>
356+
<a href="#workload-codeflare-dev-v1beta2-AppWrapperComponentStatus"><code>[]AppWrapperComponentStatus</code></a>
357+
</td>
358+
<td>
359+
<p>ComponentStatus parallels the Components array in the Spec and tracks the actually deployed resources</p>
360+
</td>
361+
</tr>
264362
</tbody>
265363
</table>
364+

‎site/genref/markdown/members.tpl

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{{ define "members" }}
2-
{{/* . is a apiType */}}
2+
{{/* . is a apiType */}}
33
{{- range .GetMembers -}}
44
{{/* . is a apiMember */}}
55
{{- if not .Hidden }}

‎site/genref/markdown/pkg.tpl

+4-8
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,18 @@
66
permalink: /api/{{ .DisplayName }}/
77
title: {{ .Title }}
88
classes: wide
9+
description: Generated API reference documentation for {{ .DisplayName }}.
910
---
1011
{{ .GetComment -}}
1112
{{- end -}}
1213
{{- end }}
1314

14-
Generated API reference documentation for {{ .GroupName }}.
15-
1615
## Resource Types
1716

1817
{{ range .packages -}}
19-
{{- range .VisibleTypes -}}
20-
{{- if .IsExported }}
18+
{{- range .VisibleTypes -}}
2119
- [{{ .DisplayName }}]({{ .Link }})
22-
{{- end -}}
23-
{{- end -}}
20+
{{ end -}}
2421
{{- end -}}
2522

2623
{{ range .packages -}}
@@ -33,9 +30,8 @@ Generated API reference documentation for {{ .GroupName }}.
3330
{{ end }}
3431
{{ else }}
3532
{{/* For package w/o group name, list only types referenced. */}}
36-
{{ $isConfig := (eq .GroupName "") }}
3733
{{- range .VisibleTypes -}}
38-
{{- if or .Referenced $isConfig -}}
34+
{{- if .Referenced -}}
3935
{{ template "type" . }}
4036
{{- end -}}
4137
{{- end }}

‎site/genref/markdown/type.tpl

+3-4
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,12 @@
2222
<table class="table">
2323
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
2424
<tbody>
25-
{{/* . is a apiType */}}
26-
{{- if .IsExported -}}
25+
{{/* . is a apiType */}}
26+
{{- if .IsExported -}}
2727
{{/* Add apiVersion and kind rows if deemed necessary */}}
2828
<tr><td><code>apiVersion</code><br/>string</td><td><code>{{- .APIGroup -}}</code></td></tr>
2929
<tr><td><code>kind</code><br/>string</td><td><code>{{- .Name.Name -}}</code></td></tr>
30-
{{ end -}}
31-
30+
{{- end -}}
3231
{{/* The actual list of members is in the following template */}}
3332
{{- template "members" . -}}
3433
</tbody>

0 commit comments

Comments
 (0)