Skip to content
This repository was archived by the owner on Sep 12, 2023. It is now read-only.

Commit 5b097fd

Browse files
gaocegegegaocegege
authored
feat: Add docs for API (#114)
* feat: Add docs Signed-off-by: cegao <[email protected]> * feat: Add doc in README Signed-off-by: cegao <[email protected]>
1 parent 3fbe0ce commit 5b097fd

File tree

8 files changed

+255
-0
lines changed

8 files changed

+255
-0
lines changed

‎README.md

+3
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ jobController := common.JobController {
4949
Note that this repo is still under construction, API compatibility is not guaranteed at this point.
5050

5151
## API Reference
52+
53+
Please refer to the [API documentation](docs/api/generated.asciidoc).
54+
5255
The API fies are located under `pkg/apis/common/v1`:
5356

5457
- [constants.go](pkg/apis/common/v1/constants.go): the constants such as label keys.

‎docs/api/autogen/config.yaml

+2
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

+20
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

+19
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

+35
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

+8
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

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
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}-g.yxqyang.asia-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}-g.yxqyang.asia-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}-g.yxqyang.asia-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}-g.yxqyang.asia-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}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-jobcondition[$$JobCondition$$]
64+
****
65+
66+
67+
68+
69+
70+
71+
72+
[id="{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-replicastatus"]
73+
==== ReplicaStatus
74+
75+
ReplicaStatus represents the current observed state of the replica.
76+
77+
.Appears In:
78+
****
79+
- xref:{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
80+
****
81+
82+
[cols="25a,75a", options="header"]
83+
|===
84+
| Field | Description
85+
| *`active`* __integer__ | The number of actively running pods.
86+
| *`succeeded`* __integer__ | The number of pods which reached phase Succeeded.
87+
| *`failed`* __integer__ | The number of pods which reached phase Failed.
88+
|===
89+
90+
91+
[id="{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-replicatype"]
92+
==== ReplicaType (string)
93+
94+
ReplicaType represents the type of the replica. Each operator needs to define its own set of ReplicaTypes.
95+
96+
.Appears In:
97+
****
98+
- xref:{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
99+
****
100+
101+
102+
103+
[id="{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-restartpolicy"]
104+
==== RestartPolicy (string)
105+
106+
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.
107+
108+
.Appears In:
109+
****
110+
- xref:{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-replicaspec[$$ReplicaSpec$$]
111+
****
112+
113+
114+
115+
116+
117+
[id="{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-schedulingpolicy"]
118+
==== SchedulingPolicy
119+
120+
SchedulingPolicy encapsulates various scheduling policies of the distributed training job, for example `minAvailable` for gang-scheduling.
121+
122+
.Appears In:
123+
****
124+
- xref:{anchor_prefix}-g.yxqyang.asia-kubeflow-common-pkg-apis-common-v1-runpolicy[$$RunPolicy$$]
125+
****
126+
127+
[cols="25a,75a", options="header"]
128+
|===
129+
| Field | Description
130+
| *`minAvailable`* __integer__ |
131+
|===
132+
133+

‎hack/generate-apidoc.sh

+35
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/common/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)