Skip to content

Commit 6d9ee32

Browse files
gaocegegegaocegege
authored
feat: Add API Documentation WIP (kubeflow#1249)
Signed-off-by: cegao <[email protected]>
1 parent fc46a92 commit 6d9ee32

File tree

8 files changed

+312
-0
lines changed

8 files changed

+312
-0
lines changed

‎README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,10 @@ kubectl apply -f ./deploy/v1/tf-operator.yaml
2727

2828
Please refer to the [quick-start-v1.md](docs/quick-start-v1.md) and [Kubeflow user guide](https://www.kubeflow.org/docs/guides/components/tftraining/) for more information.
2929

30+
## API Documentation
31+
32+
Please refer to [API Documentation](docs/api/generated.asciidoc)
33+
3034
## Community
3135

3236
You can:

‎docs/api/autogen/config.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
render:
2+
kubernetesVersion: "1.16"

‎docs/api/autogen/templates/gv_details.tpl

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

‎docs/api/autogen/templates/gv_list.tpl

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{{- define "gvList" -}}
2+
{{- $groupVersions := . -}}
3+
4+
// Generated documentation. Please do not edit.
5+
:anchor_prefix: k8s-api
6+
7+
[id="{p}-api-reference"]
8+
= API Reference
9+
10+
.Packages
11+
{{- range $groupVersions }}
12+
- {{ asciidocRenderGVLink . }}
13+
{{- end }}
14+
15+
{{ range $groupVersions }}
16+
{{ template "gvDetails" . }}
17+
{{ end }}
18+
19+
{{- end -}}

‎docs/api/autogen/templates/type.tpl

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{{- define "type" -}}
2+
{{- $type := . -}}
3+
{{- if asciidocShouldRenderType $type -}}
4+
5+
[id="{{ asciidocTypeID $type | asciidocRenderAnchorID }}"]
6+
==== {{ $type.Name }} {{ if $type.IsAlias }}({{ asciidocRenderTypeLink $type.UnderlyingType }}) {{ end }}
7+
8+
{{ $type.Doc }}
9+
10+
{{ if $type.References -}}
11+
.Appears In:
12+
****
13+
{{- range $type.SortedReferences }}
14+
- {{ asciidocRenderTypeLink . }}
15+
{{- end }}
16+
****
17+
{{- end }}
18+
19+
{{ if $type.Members -}}
20+
[cols="25a,75a", options="header"]
21+
|===
22+
| Field | Description
23+
{{ if $type.GVK -}}
24+
| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
25+
| *`kind`* __string__ | `{{ $type.GVK.Kind }}`
26+
{{ end -}}
27+
28+
{{ range $type.Members -}}
29+
| *`{{ .Name }}`* __{{ asciidocRenderType .Type }}__ | {{ template "type_members" . }}
30+
{{ end -}}
31+
|===
32+
{{ end -}}
33+
34+
{{- end -}}
35+
{{- end -}}

‎docs/api/autogen/templates/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+
{{ $field.Doc }}
7+
{{- end -}}
8+
{{- end -}}

‎docs/api/generated.asciidoc

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
// Generated documentation. Please do not edit.
2+
:anchor_prefix: k8s-api
3+
4+
[id="{p}-api-reference"]
5+
= API Reference
6+
7+
.Packages
8+
- xref:{anchor_prefix}-kubeflow-org-v1[$$kubeflow.org/v1$$]
9+
10+
11+
[id="{anchor_prefix}-kubeflow-org-v1"]
12+
== kubeflow.org/v1
13+
14+
Package v1 is the v1 version of the API.
15+
16+
17+
Licensed under the Apache License, Version 2.0 (the "License");
18+
you may not use this file except in compliance with the License.
19+
You may obtain a copy of the License at
20+
21+
http://www.apache.org/licenses/LICENSE-2.0
22+
23+
Unless required by applicable law or agreed to in writing, software
24+
distributed under the License is distributed on an "AS IS" BASIS,
25+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
26+
See the License for the specific language governing permissions and
27+
limitations under the License.
28+
29+
30+
=== Definitions
31+
32+
33+
34+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobcondition"]
35+
==== JobCondition
36+
37+
JobCondition describes the state of the job at a certain point.
38+
39+
.Appears In:
40+
****
41+
- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
42+
****
43+
44+
[cols="25a,75a", options="header"]
45+
|===
46+
| Field | Description
47+
| *`type`* __xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobconditiontype[$$JobConditionType$$]__ | Type of job condition.
48+
| *`status`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#conditionstatus-v1-core[$$ConditionStatus$$]__ | Status of the condition, one of True, False, Unknown.
49+
| *`reason`* __string__ | The reason for the condition's last transition.
50+
| *`message`* __string__ | A human readable message indicating details about the transition.
51+
| *`lastUpdateTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#time-v1-meta[$$Time$$]__ | The last time this condition was updated.
52+
| *`lastTransitionTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#time-v1-meta[$$Time$$]__ | Last time the condition transitioned from one status to another.
53+
|===
54+
55+
56+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobconditiontype"]
57+
==== JobConditionType (string)
58+
59+
JobConditionType defines all kinds of types of JobStatus.
60+
61+
.Appears In:
62+
****
63+
- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobcondition[$$JobCondition$$]
64+
****
65+
66+
67+
68+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus"]
69+
==== JobStatus
70+
71+
JobStatus represents the current observed state of the training Job.
72+
73+
.Appears In:
74+
****
75+
- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjob[$$TFJob$$]
76+
****
77+
78+
[cols="25a,75a", options="header"]
79+
|===
80+
| Field | Description
81+
| *`conditions`* __xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobcondition[$$JobCondition$$] array__ | Conditions is an array of current observed job conditions.
82+
| *`replicaStatuses`* __object (keys:xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicatype[$$ReplicaType$$], values:xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicastatus[$$ReplicaStatus$$])__ | ReplicaStatuses is map of ReplicaType and ReplicaStatus, specifies the status of each replica.
83+
| *`startTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#time-v1-meta[$$Time$$]__ | Represents time when the job was acknowledged by the job controller. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC.
84+
| *`completionTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#time-v1-meta[$$Time$$]__ | Represents time when the job was completed. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC.
85+
| *`lastReconcileTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#time-v1-meta[$$Time$$]__ | Represents last time when the job was reconciled. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC.
86+
|===
87+
88+
89+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicaspec"]
90+
==== ReplicaSpec
91+
92+
ReplicaSpec is a description of the replica
93+
94+
.Appears In:
95+
****
96+
- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjobspec[$$TFJobSpec$$]
97+
****
98+
99+
[cols="25a,75a", options="header"]
100+
|===
101+
| Field | Description
102+
| *`replicas`* __integer__ | Replicas is the desired number of replicas of the given template. If unspecified, defaults to 1.
103+
| *`template`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#podtemplatespec-v1-core[$$PodTemplateSpec$$]__ | Template is the object that describes the pod that will be created for this replica. RestartPolicy in PodTemplateSpec will be overide by RestartPolicy in ReplicaSpec
104+
| *`restartPolicy`* __xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-restartpolicy[$$RestartPolicy$$]__ | Restart policy for all replicas within the job. One of Always, OnFailure, Never and ExitCode. Default to Never.
105+
|===
106+
107+
108+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicastatus"]
109+
==== ReplicaStatus
110+
111+
ReplicaStatus represents the current observed state of the replica.
112+
113+
.Appears In:
114+
****
115+
- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
116+
****
117+
118+
[cols="25a,75a", options="header"]
119+
|===
120+
| Field | Description
121+
| *`active`* __integer__ | The number of actively running pods.
122+
| *`succeeded`* __integer__ | The number of pods which reached phase Succeeded.
123+
| *`failed`* __integer__ | The number of pods which reached phase Failed.
124+
|===
125+
126+
127+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicatype"]
128+
==== ReplicaType (string)
129+
130+
ReplicaType represents the type of the replica. Each operator needs to define its own set of ReplicaTypes.
131+
132+
.Appears In:
133+
****
134+
- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
135+
- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjobspec[$$TFJobSpec$$]
136+
****
137+
138+
139+
140+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-restartpolicy"]
141+
==== RestartPolicy (string)
142+
143+
RestartPolicy describes how the replicas should be restarted. Only one of the following restart policies may be specified. If none of the following policies is specified, the default one is RestartPolicyAlways.
144+
145+
.Appears In:
146+
****
147+
- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicaspec[$$ReplicaSpec$$]
148+
****
149+
150+
151+
152+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-runpolicy"]
153+
==== RunPolicy
154+
155+
RunPolicy encapsulates various runtime policies of the distributed training job, for example how to clean up resources and how long the job can stay active.
156+
157+
.Appears In:
158+
****
159+
- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjobspec[$$TFJobSpec$$]
160+
****
161+
162+
[cols="25a,75a", options="header"]
163+
|===
164+
| Field | Description
165+
| *`cleanPodPolicy`* __CleanPodPolicy__ | CleanPodPolicy defines the policy to kill pods after the job completes. Default to Running.
166+
| *`ttlSecondsAfterFinished`* __integer__ | TTLSecondsAfterFinished is the TTL to clean up jobs. It may take extra ReconcilePeriod seconds for the cleanup, since reconcile gets called periodically. Default to infinite.
167+
| *`activeDeadlineSeconds`* __integer__ | Specifies the duration in seconds relative to the startTime that the job may be active before the system tries to terminate it; value must be positive integer.
168+
| *`backoffLimit`* __integer__ | Optional number of retries before marking this job failed.
169+
| *`schedulingPolicy`* __xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-schedulingpolicy[$$SchedulingPolicy$$]__ | SchedulingPolicy defines the policy related to scheduling, e.g. gang-scheduling
170+
|===
171+
172+
173+
[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-schedulingpolicy"]
174+
==== SchedulingPolicy
175+
176+
SchedulingPolicy encapsulates various scheduling policies of the distributed training job, for example `minAvailable` for gang-scheduling.
177+
178+
.Appears In:
179+
****
180+
- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-runpolicy[$$RunPolicy$$]
181+
****
182+
183+
[cols="25a,75a", options="header"]
184+
|===
185+
| Field | Description
186+
| *`minAvailable`* __integer__ |
187+
|===
188+
189+

‎hack/generate-apidoc.sh

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
#!/bin/bash
2+
3+
# Copyright 2017 The Kubernetes Authors.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
# This shell is used to auto generate some useful tools for k8s, such as lister,
18+
# informer, deepcopy, defaulter and so on.
19+
20+
set -o errexit
21+
set -o nounset
22+
set -o pipefail
23+
24+
SCRIPT_ROOT=$(dirname ${BASH_SOURCE})/..
25+
26+
cd ${SCRIPT_ROOT}
27+
28+
crd-ref-docs --log-level DEBUG\
29+
--source-path ./pkg/apis/tensorflow/v1 \
30+
--config ./docs/api/autogen/config.yaml \
31+
--templates-dir ./docs/api/autogen/templates \
32+
--output-path ./docs/api/generated.asciidoc \
33+
--max-depth 30
34+
35+
cd - > /dev/null

0 commit comments

Comments
 (0)