feat: Add API Documentation

README.md

@@ -27,6 +27,10 @@ kubectl apply -f ./deploy/v1/tf-operator.yaml
 
 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.
 
+## API Documentation
+
+Please refer to [API Documentation](docs/api/generated.asciidoc)
+
 ## Community
 
 You can:

docs/api/autogen/config.yaml

@@ -0,0 +1,2 @@
+render:
+  kubernetesVersion: "1.16"

docs/api/autogen/templates/gv_details.tpl

@@ -0,0 +1,20 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+[id="{{ asciidocGroupVersionID $gv | asciidocRenderAnchorID }}"]
+== {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+.Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | asciidocRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+=== Definitions
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

docs/api/autogen/templates/gv_list.tpl

@@ -0,0 +1,19 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+// Generated documentation. Please do not edit.
+:anchor_prefix: k8s-api
+
+[id="{p}-api-reference"]
+= API Reference
+
+.Packages
+{{- range $groupVersions }}
+- {{ asciidocRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

docs/api/autogen/templates/type.tpl

@@ -0,0 +1,35 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if asciidocShouldRenderType $type -}}
+
+[id="{{ asciidocTypeID $type | asciidocRenderAnchorID }}"]
+==== {{ $type.Name  }} {{ if $type.IsAlias }}({{ asciidocRenderTypeLink $type.UnderlyingType  }}) {{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.References -}}
+.Appears In:
+****
+{{- range $type.SortedReferences }}
+- {{ asciidocRenderTypeLink . }}
+{{- end }}
+****
+{{- end }}
+
+{{ if $type.Members -}}
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+{{ if $type.GVK -}}
+| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}`
+| *`kind`* __string__ | `{{ $type.GVK.Kind }}`
+{{ end -}}
+
+{{ range $type.Members -}}
+| *`{{ .Name  }}`* __{{ asciidocRenderType .Type }}__ | {{ template "type_members" . }}
+{{ end -}}
+|===
+{{ end -}}
+
+{{- end -}}
+{{- end -}}

docs/api/autogen/templates/type_members.tpl

@@ -0,0 +1,8 @@
+{{- define "type_members" -}}
+{{- $field := . -}}
+{{- if eq $field.Name "metadata" -}}
+Refer to Kubernetes API documentation for fields of `metadata`.
+{{ else -}}
+{{ $field.Doc }}
+{{- end -}}
+{{- end -}}

docs/api/generated.asciidoc

@@ -0,0 +1,189 @@
+// Generated documentation. Please do not edit.
+:anchor_prefix: k8s-api
+
+[id="{p}-api-reference"]
+= API Reference
+
+.Packages
+- xref:{anchor_prefix}-kubeflow-org-v1[$$kubeflow.org/v1$$]
+
+
+[id="{anchor_prefix}-kubeflow-org-v1"]
+== kubeflow.org/v1
+
+Package v1 is the v1 version of the API.
+
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+=== Definitions
+
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobcondition"]
+==== JobCondition 
+
+JobCondition describes the state of the job at a certain point.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`type`* __xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobconditiontype[$$JobConditionType$$]__ | Type of job condition.
+| *`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.
+| *`reason`* __string__ | The reason for the condition's last transition.
+| *`message`* __string__ | A human readable message indicating details about the transition.
+| *`lastUpdateTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#time-v1-meta[$$Time$$]__ | The last time this condition was updated.
+| *`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.
+|===
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobconditiontype"]
+==== JobConditionType (string) 
+
+JobConditionType defines all kinds of types of JobStatus.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobcondition[$$JobCondition$$]
+****
+
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus"]
+==== JobStatus 
+
+JobStatus represents the current observed state of the training Job.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjob[$$TFJob$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`conditions`* __xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobcondition[$$JobCondition$$] array__ | Conditions is an array of current observed job conditions.
+| *`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.
+| *`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.
+| *`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.
+| *`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.
+|===
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicaspec"]
+==== ReplicaSpec 
+
+ReplicaSpec is a description of the replica
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjobspec[$$TFJobSpec$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`replicas`* __integer__ | Replicas is the desired number of replicas of the given template. If unspecified, defaults to 1.
+| *`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
+| *`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.
+|===
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicastatus"]
+==== ReplicaStatus 
+
+ReplicaStatus represents the current observed state of the replica.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`active`* __integer__ | The number of actively running pods.
+| *`succeeded`* __integer__ | The number of pods which reached phase Succeeded.
+| *`failed`* __integer__ | The number of pods which reached phase Failed.
+|===
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicatype"]
+==== ReplicaType (string) 
+
+ReplicaType represents the type of the replica. Each operator needs to define its own set of ReplicaTypes.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-jobstatus[$$JobStatus$$]
+- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjobspec[$$TFJobSpec$$]
+****
+
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-restartpolicy"]
+==== RestartPolicy (string) 
+
+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.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-replicaspec[$$ReplicaSpec$$]
+****
+
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-runpolicy"]
+==== RunPolicy 
+
+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.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-tf-operator-pkg-apis-tensorflow-v1-tfjobspec[$$TFJobSpec$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`cleanPodPolicy`* __CleanPodPolicy__ | CleanPodPolicy defines the policy to kill pods after the job completes. Default to Running.
+| *`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.
+| *`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.
+| *`backoffLimit`* __integer__ | Optional number of retries before marking this job failed.
+| *`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
+|===
+
+
+[id="{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-schedulingpolicy"]
+==== SchedulingPolicy 
+
+SchedulingPolicy encapsulates various scheduling policies of the distributed training job, for example `minAvailable` for gang-scheduling.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-kubeflow-common-pkg-apis-common-v1-runpolicy[$$RunPolicy$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`minAvailable`* __integer__ | 
+|===
+
+

hack/generate-apidoc.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# Copyright 2017 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This shell is used to auto generate some useful tools for k8s, such as lister,
+# informer, deepcopy, defaulter and so on.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+SCRIPT_ROOT=$(dirname ${BASH_SOURCE})/..
+
+cd ${SCRIPT_ROOT}
+
+crd-ref-docs --log-level DEBUG\
+    --source-path ./pkg/apis/tensorflow/v1 \
+		--config ./docs/api/autogen/config.yaml \
+		--templates-dir ./docs/api/autogen/templates \
+		--output-path ./docs/api/generated.asciidoc \
+		--max-depth 30
+
+cd - > /dev/null