Skip to content

Commit 0249915

Browse files
ironcladlouironcladlou
committed
Improve API reference docs
This commit updates API documentation on the Go types and also improves the generated API documentation to include only the public types, as well as other minor small fixes for readability. Note that the `+gencopy` comments added to the API types are to work around an issue[1] in the upstream docs generation code which doesn't yet understand the `+kubebuilder:object:root` tag. This is necessary to make the generator understand which types are "public" (e.g. HostedCluster and NodePool). [1] ahmetb/gen-crd-api-reference-docs#26
1 parent 0bb7d4f commit 0249915

File tree

11 files changed

+1186
-1509
lines changed

11 files changed

+1186
-1509
lines changed

‎api/v1alpha1/doc.go‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,14 @@
1-
// Package v1alpha1 contains API Schema definitions for the hypershift.openshift.io v1alpha1 API group
1+
/*
2+
Package v1alpha1 contains the HyperShift API.
3+
4+
The HyperShift API enables creating and managing lightweight, flexible, heterogeneous
5+
OpenShift clusters at scale.
6+
7+
HyperShift clusters are deployed in a topology which isolates the "control plane"
8+
(e.g. etcd, the API server, controller manager, etc.) from the "data plane" (e.g.
9+
worker nodes and their kubelets, and the infrastructure on which they run). This
10+
enables "hosted control plane as a service" use cases.
11+
*/
212
// +kubebuilder:object:generate=true
313
// +groupName=hypershift.openshift.io
414
package v1alpha1

‎api/v1alpha1/hosted_controlplane.go‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,21 @@ type HostedControlPlaneSpec struct {
9797
SecretEncryption *SecretEncryptionSpec `json:"secretEncryption,omitempty"`
9898
}
9999

100+
// AvailabilityPolicy specifies a high level availability policy for components.
100101
type AvailabilityPolicy string
101102

102103
const (
104+
// HighlyAvailable means components should be resilient to problems across fault
105+
// boundaries as defined by the component to which the policy is attached. This
106+
// usually means running critical workloads with 3 replicas and with little or
107+
// no toleration of disruption of the component.
103108
HighlyAvailable AvailabilityPolicy = "HighlyAvailable"
104-
SingleReplica AvailabilityPolicy = "SingleReplica"
109+
110+
// SingleReplica means components are not expected to be resilient to problems
111+
// across most fault boundaries associated with high availability. This usually
112+
// means running critical workloads with just 1 replica and with toleration of
113+
// full disruption of the component.
114+
SingleReplica AvailabilityPolicy = "SingleReplica"
105115
)
106116

107117
type KubeconfigSecretRef struct {

‎api/v1alpha1/hostedcluster_types.go‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,8 @@ type HostedClusterSpec struct {
129129
// TODO (alberto): include Ignition endpoint here.
130130
Services []ServicePublishingStrategyMapping `json:"services"`
131131

132-
// ControllerAvailabilityPolicy specifies whether to run control plane controllers in HA mode
132+
// ControllerAvailabilityPolicy specifies an availability policy to apply
133+
// to critical control plane components.
133134
// Defaults to SingleReplica when not set.
134135
// +optional
135136
ControllerAvailabilityPolicy AvailabilityPolicy `json:"controllerAvailabilityPolicy,omitempty"`
@@ -841,6 +842,14 @@ type ClusterConfiguration struct {
841842
Items []runtime.RawExtension `json:"items,omitempty"`
842843
}
843844

845+
// +genclient
846+
847+
// HostedCluster is the primary representation of a HyperShift cluster and encapsulates
848+
// the control plane and common data plane configuration. Creating a HostedCluster
849+
// results in a fully functional OpenShift control plane with no attached nodes.
850+
// To support workloads (e.g. pods), a HostedCluster may have one or more associated
851+
// NodePool resources.
852+
//
844853
// +kubebuilder:object:root=true
845854
// +kubebuilder:resource:path=hostedclusters,shortName=hc;hcs,scope=Namespaced
846855
// +kubebuilder:storageversion
@@ -850,12 +859,14 @@ type ClusterConfiguration struct {
850859
// +kubebuilder:printcolumn:name="Progress",type="string",JSONPath=".status.version.history[?(@.state!=\"\")].state",description="Progress"
851860
// +kubebuilder:printcolumn:name="Available",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].status",description="Available"
852861
// +kubebuilder:printcolumn:name="Reason",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].reason",description="Reason"
853-
// HostedCluster is the Schema for the hostedclusters API
854862
type HostedCluster struct {
855863
metav1.TypeMeta `json:",inline"`
856864
metav1.ObjectMeta `json:"metadata,omitempty"`
857865

858-
Spec HostedClusterSpec `json:"spec,omitempty"`
866+
// Spec is the desired behavior of the HostedCluster.
867+
Spec HostedClusterSpec `json:"spec,omitempty"`
868+
869+
// Status is the latest observed status of the HostedCluster.
859870
Status HostedClusterStatus `json:"status,omitempty"`
860871
}
861872

‎api/v1alpha1/nodepool_types.go‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,12 @@ func init() {
3030
SchemeBuilder.Register(&NodePoolList{})
3131
}
3232

33-
// NodePool defines the desired state of NodePool
33+
// +genclient
34+
35+
// NodePool is a scalable set of worker nodes attached to a HostedCluster. NodePool
36+
// machine architectures are uniform within a given pool, and are independent of
37+
// the control plane’s underlying machine architecture.
38+
//
3439
// +kubebuilder:resource:path=nodepools,shortName=np;nps,scope=Namespaced
3540
// +kubebuilder:storageversion
3641
// +kubebuilder:subresource:status
@@ -47,7 +52,10 @@ type NodePool struct {
4752
metav1.TypeMeta `json:",inline"`
4853
metav1.ObjectMeta `json:"metadata,omitempty"`
4954

50-
Spec NodePoolSpec `json:"spec,omitempty"`
55+
// Spec is the desired behavior of the NodePool.
56+
Spec NodePoolSpec `json:"spec,omitempty"`
57+
58+
// Status is the most recently observed status of the NodePool.
5159
Status NodePoolStatus `json:"status,omitempty"`
5260
}
5361

‎cmd/install/assets/hypershift-operator/hypershift.openshift.io_hostedclusters.yaml‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,11 @@ spec:
4343
name: v1alpha1
4444
schema:
4545
openAPIV3Schema:
46-
description: HostedCluster is the Schema for the hostedclusters API
46+
description: HostedCluster is the primary representation of a HyperShift cluster
47+
and encapsulates the control plane and common data plane configuration.
48+
Creating a HostedCluster results in a fully functional OpenShift control
49+
plane with no attached nodes. To support workloads (e.g. pods), a HostedCluster
50+
may have one or more associated NodePool resources.
4751
properties:
4852
apiVersion:
4953
description: 'APIVersion defines the versioned schema of this representation
@@ -58,7 +62,7 @@ spec:
5862
metadata:
5963
type: object
6064
spec:
61-
description: HostedClusterSpec defines the desired state of HostedCluster
65+
description: Spec is the desired behavior of the HostedCluster.
6266
properties:
6367
auditWebhook:
6468
description: AuditWebhook contains metadata for configuring an audit
@@ -144,9 +148,9 @@ spec:
144148
type: array
145149
type: object
146150
controllerAvailabilityPolicy:
147-
description: ControllerAvailabilityPolicy specifies whether to run
148-
control plane controllers in HA mode Defaults to SingleReplica when
149-
not set.
151+
description: ControllerAvailabilityPolicy specifies an availability
152+
policy to apply to critical control plane components. Defaults to
153+
SingleReplica when not set.
150154
type: string
151155
dns:
152156
description: DNS configuration for the cluster
@@ -813,7 +817,7 @@ spec:
813817
- sshKey
814818
type: object
815819
status:
816-
description: HostedClusterStatus defines the observed state of HostedCluster
820+
description: Status is the latest observed status of the HostedCluster.
817821
properties:
818822
conditions:
819823
items:

‎cmd/install/assets/hypershift-operator/hypershift.openshift.io_nodepools.yaml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,9 @@ spec:
5151
name: v1alpha1
5252
schema:
5353
openAPIV3Schema:
54-
description: NodePool defines the desired state of NodePool
54+
description: NodePool is a scalable set of worker nodes attached to a HostedCluster.
55+
NodePool machine architectures are uniform within a given pool, and are
56+
independent of the control plane’s underlying machine architecture.
5557
properties:
5658
apiVersion:
5759
description: 'APIVersion defines the versioned schema of this representation
@@ -66,7 +68,7 @@ spec:
6668
metadata:
6769
type: object
6870
spec:
69-
description: NodePoolSpec defines the desired state of NodePool
71+
description: Spec is the desired behavior of the NodePool.
7072
properties:
7173
autoScaling:
7274
properties:
@@ -325,7 +327,7 @@ spec:
325327
- release
326328
type: object
327329
status:
328-
description: NodePoolStatus defines the observed state of NodePool
330+
description: Status is the most recently observed status of the NodePool.
329331
properties:
330332
conditions:
331333
items:

‎docs/api-doc-gen/config.json‎

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,29 @@
11
{
22
"hideMemberFields": [
3-
"TypeMeta"
3+
"TypeMeta"
44
],
55
"hideTypePatterns": [
6-
"ParseError$",
7-
"List$"
6+
"ParseError$",
7+
"List$",
8+
"HostedControlPlane*$",
9+
"KubeconfigSecretRef",
10+
"APIEndpoint",
11+
"AWSEndpointService*"
812
],
913
"externalPackages": [
10-
{
11-
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
12-
"docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
13-
},
14-
{
15-
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
16-
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
17-
}
14+
{
15+
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
16+
"docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
17+
},
18+
{
19+
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
20+
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
21+
}
1822
],
1923
"typeDisplayNamePrefixOverrides": {
20-
"k8s.io/api/": "Kubernetes ",
21-
"k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
22-
"k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
24+
"k8s.io/api/": "Kubernetes ",
25+
"k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
26+
"k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
2327
},
2428
"markdownDisabled": false
2529
}

‎docs/api-doc-gen/templates/pkg.tpl‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,17 +29,6 @@ title: API Reference
2929
{{ end }}
3030
{{ end }}
3131

32-
Resource Types:
33-
<ul>
34-
{{- range (visibleTypes (sortedTypes .Types)) -}}
35-
{{ if isExportedType . -}}
36-
<li>
37-
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
38-
</li>
39-
{{- end }}
40-
{{- end -}}
41-
</ul>
42-
4332
{{ range (visibleTypes (sortedTypes .Types))}}
4433
{{ template "type" . }}
4534
{{ end }}

‎docs/api-doc-gen/templates/type.tpl‎

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
{{ define "type" }}
22

3-
<h3 id="{{ anchorIDForType . }}">
4-
{{- .Name.Name }}
5-
{{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
6-
</h3>
3+
{{ if isExportedType . -}}
4+
## {{- .Name.Name }} { #{{ anchorIDForType . }} }
5+
{{ else -}}
6+
### {{- .Name.Name }} { #{{ anchorIDForType . }} }
7+
{{ end -}}
8+
79
{{ with (typeReferences .) }}
810
<p>
911
(<em>Appears on:</em>
@@ -22,6 +24,30 @@
2224
{{ safe (renderComments .CommentLines) }}
2325
</p>
2426

27+
{{ with (constantsOfType .) }}
28+
<table>
29+
<thead>
30+
<tr>
31+
<th>Value</th>
32+
<th>Description</th>
33+
</tr>
34+
</thead>
35+
<tbody>
36+
{{- range . -}}
37+
<tr>
38+
{{- /*
39+
renderComments implicitly creates a <p> element, so we
40+
add one to the display name as well to make the contents
41+
of the two cells align evenly.
42+
*/ -}}
43+
<td><p>{{ typeDisplayName . }}</p></td>
44+
<td>{{ safe (renderComments .CommentLines) }}</td>
45+
</tr>
46+
{{- end -}}
47+
</tbody>
48+
</table>
49+
{{ end }}
50+
2551
{{ if .Members }}
2652
<table>
2753
<thead>

0 commit comments

Comments
 (0)