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
ironcladlou · Nov 10, 2021 · f69d933 · f69d933
1 parent 00ee359
commit f69d933
Show file tree

Hide file tree

Showing 11 changed files with 1,175 additions and 1,511 deletions.
diff --git a/api/v1alpha1/doc.go b/api/v1alpha1/doc.go
@@ -8,9 +8,6 @@ HyperShift clusters are deployed in a topology which isolates the "control plane
 (e.g. etcd, the API server, controller manager, etc.) from the "data plane" (e.g.
 worker nodes and their kubelets, and the infrastructure on which they run). This
 enables "hosted control plane as a service" use cases.
-
-The API is represented as Kubernetes Custom Resource Definitions in the
-hypershift.openshift.io API group.
 */
 // +kubebuilder:object:generate=true
 // +groupName=hypershift.openshift.io

diff --git a/api/v1alpha1/hosted_controlplane.go b/api/v1alpha1/hosted_controlplane.go
@@ -97,11 +97,21 @@ type HostedControlPlaneSpec struct {
 	SecretEncryption *SecretEncryptionSpec `json:"secretEncryption,omitempty"`
 }
 
+// AvailabilityPolicy specifies a high level availability policy for components.
 type AvailabilityPolicy string
 
 const (
+	// HighlyAvailable means components should be resilient to problems across fault
+	// boundaries as defined by the component to which the policy is attached. This
+	// usually means running critical workloads with 3 replicas and with little or
+	// no toleration of disruption of the component.
 	HighlyAvailable AvailabilityPolicy = "HighlyAvailable"
-	SingleReplica   AvailabilityPolicy = "SingleReplica"
+
+	// SingleReplica means components are not expected to be resilient to problems
+	// across most fault boundaries associated with high availability. This usually
+	// means running critical workloads with just 1 replica and with toleration of
+	// full disruption of the component.
+	SingleReplica AvailabilityPolicy = "SingleReplica"
 )
 
 type KubeconfigSecretRef struct {

diff --git a/api/v1alpha1/hostedcluster_types.go b/api/v1alpha1/hostedcluster_types.go
@@ -129,7 +129,8 @@ type HostedClusterSpec struct {
 	// TODO (alberto): include Ignition endpoint here.
 	Services []ServicePublishingStrategyMapping `json:"services"`
 
-	// ControllerAvailabilityPolicy specifies whether to run control plane controllers in HA mode
+	// ControllerAvailabilityPolicy specifies an availability policy to apply
+	// to critical control plane components.
 	// Defaults to SingleReplica when not set.
 	// +optional
 	ControllerAvailabilityPolicy AvailabilityPolicy `json:"controllerAvailabilityPolicy,omitempty"`
@@ -832,6 +833,14 @@ type ClusterConfiguration struct {
 	Items []runtime.RawExtension `json:"items,omitempty"`
 }
 
+// +genclient
+
+// HostedCluster is the primary representation of a HyperShift cluster and encapsulates
+// the control plane and common data plane configuration. Creating a HostedCluster
+// results in a fully functional OpenShift control plane with no attached nodes.
+// To support workloads (e.g. pods), a HostedCluster may have one or more associated
+// NodePool resources.
+//
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:path=hostedclusters,shortName=hc;hcs,scope=Namespaced
 // +kubebuilder:storageversion
@@ -841,12 +850,14 @@ type ClusterConfiguration struct {
 // +kubebuilder:printcolumn:name="Progress",type="string",JSONPath=".status.version.history[?(@.state!=\"\")].state",description="Progress"
 // +kubebuilder:printcolumn:name="Available",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].status",description="Available"
 // +kubebuilder:printcolumn:name="Reason",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].reason",description="Reason"
-// HostedCluster is the Schema for the hostedclusters API
 type HostedCluster struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   HostedClusterSpec   `json:"spec,omitempty"`
+	// Spec is the desired behavior of the HostedCluster.
+	Spec HostedClusterSpec `json:"spec,omitempty"`
+
+	// Status is the latest observed status of the HostedCluster.
 	Status HostedClusterStatus `json:"status,omitempty"`
 }
 

diff --git a/api/v1alpha1/nodepool_types.go b/api/v1alpha1/nodepool_types.go
@@ -30,7 +30,12 @@ func init() {
 	SchemeBuilder.Register(&NodePoolList{})
 }
 
-// NodePool defines the desired state of NodePool
+// +genclient
+
+// NodePool is a scalable set of worker nodes attached to a HostedCluster. NodePool
+// machine architectures are uniform within a given pool, and are independent of
+// the control plane’s underlying machine architecture.
+//
 // +kubebuilder:resource:path=nodepools,shortName=np;nps,scope=Namespaced
 // +kubebuilder:storageversion
 // +kubebuilder:subresource:status
@@ -47,7 +52,10 @@ type NodePool struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   NodePoolSpec   `json:"spec,omitempty"`
+	// Spec is the desired behavior of the NodePool.
+	Spec NodePoolSpec `json:"spec,omitempty"`
+
+	// Status is the most recently observed status of the NodePool.
 	Status NodePoolStatus `json:"status,omitempty"`
 }
 

diff --git a/cmd/install/assets/hypershift-operator/hypershift.openshift.io_hostedclusters.yaml b/cmd/install/assets/hypershift-operator/hypershift.openshift.io_hostedclusters.yaml
@@ -43,7 +43,11 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: HostedCluster is the Schema for the hostedclusters API
+        description: HostedCluster is the primary representation of a HyperShift cluster
+          and encapsulates the control plane and common data plane configuration.
+          Creating a HostedCluster results in a fully functional OpenShift control
+          plane with no attached nodes. To support workloads (e.g. pods), a HostedCluster
+          may have one or more associated NodePool resources.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -58,7 +62,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: HostedClusterSpec defines the desired state of HostedCluster
+            description: Spec is the desired behavior of the HostedCluster.
             properties:
               auditWebhook:
                 description: AuditWebhook contains metadata for configuring an audit
@@ -144,9 +148,9 @@ spec:
                     type: array
                 type: object
               controllerAvailabilityPolicy:
-                description: ControllerAvailabilityPolicy specifies whether to run
-                  control plane controllers in HA mode Defaults to SingleReplica when
-                  not set.
+                description: ControllerAvailabilityPolicy specifies an availability
+                  policy to apply to critical control plane components. Defaults to
+                  SingleReplica when not set.
                 type: string
               dns:
                 description: DNS configuration for the cluster
@@ -812,7 +816,7 @@ spec:
             - sshKey
             type: object
           status:
-            description: HostedClusterStatus defines the observed state of HostedCluster
+            description: Status is the latest observed status of the HostedCluster.
             properties:
               conditions:
                 items:

diff --git a/cmd/install/assets/hypershift-operator/hypershift.openshift.io_nodepools.yaml b/cmd/install/assets/hypershift-operator/hypershift.openshift.io_nodepools.yaml
@@ -51,7 +51,9 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: NodePool defines the desired state of NodePool
+        description: NodePool is a scalable set of worker nodes attached to a HostedCluster.
+          NodePool machine architectures are uniform within a given pool, and are
+          independent of the control plane’s underlying machine architecture.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -66,7 +68,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodePoolSpec defines the desired state of NodePool
+            description: Spec is the desired behavior of the NodePool.
             properties:
               autoScaling:
                 properties:
@@ -325,7 +327,7 @@ spec:
             - release
             type: object
           status:
-            description: NodePoolStatus defines the observed state of NodePool
+            description: Status is the most recently observed status of the NodePool.
             properties:
               conditions:
                 items:

diff --git a/docs/api-doc-gen/config.json b/docs/api-doc-gen/config.json
@@ -1,25 +1,29 @@
 {
   "hideMemberFields": [
-      "TypeMeta"
+    "TypeMeta"
   ],
   "hideTypePatterns": [
-      "ParseError$",
-      "List$"
+    "ParseError$",
+    "List$",
+    "HostedControlPlane*$",
+    "KubeconfigSecretRef",
+    "APIEndpoint",
+    "AWSEndpointService*"
   ],
   "externalPackages": [
-      {
-          "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
-          "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
-      },
-      {
-          "typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
-          "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
-      }
+    {
+      "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
+      "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
+    },
+    {
+      "typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
+      "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
+    }
   ],
   "typeDisplayNamePrefixOverrides": {
-      "k8s.io/api/": "Kubernetes ",
-      "k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
-      "k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
+    "k8s.io/api/": "Kubernetes ",
+    "k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
+    "k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
   },
   "markdownDisabled": false
 }
diff --git a/docs/api-doc-gen/templates/pkg.tpl b/docs/api-doc-gen/templates/pkg.tpl
@@ -29,17 +29,6 @@ title: API Reference
         {{ end }}
     {{ end }}
 
-    Resource Types:
-    <ul>
-    {{- range (visibleTypes (sortedTypes .Types)) -}}
-        {{ if isExportedType . -}}
-        <li>
-            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
-        </li>
-        {{- end }}
-    {{- end -}}
-    </ul>
-
     {{ range (visibleTypes (sortedTypes .Types))}}
         {{ template "type" .  }}
     {{ end }}

diff --git a/docs/api-doc-gen/templates/type.tpl b/docs/api-doc-gen/templates/type.tpl
@@ -1,9 +1,11 @@
 {{ define "type" }}
 
-<h3 id="{{ anchorIDForType . }}">
-    {{- .Name.Name }}
-    {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
-</h3>
+{{ if isExportedType . -}}
+## {{- .Name.Name }} { #{{ anchorIDForType . }} }
+{{ else -}}
+### {{- .Name.Name }} { #{{ anchorIDForType . }} }
+{{ end -}}
+
 {{ with (typeReferences .) }}
     <p>
         (<em>Appears on:</em>
@@ -22,6 +24,30 @@
     {{ safe (renderComments .CommentLines) }}
 </p>
 
+{{ with (constantsOfType .) }}
+<table>
+    <thead>
+        <tr>
+            <th>Value</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+      {{- range . -}}
+      <tr>
+        {{- /*
+            renderComments implicitly creates a <p> element, so we
+            add one to the display name as well to make the contents
+            of the two cells align evenly.
+        */ -}}
+        <td><p>{{ typeDisplayName . }}</p></td>
+        <td>{{ safe (renderComments .CommentLines) }}</td>
+      </tr>
+      {{- end -}}
+    </tbody>
+</table>
+{{ end }}
+
 {{ if .Members }}
 <table>
     <thead>