From 9dab06c4c95dc760396c5002208263bb5d3f3cf3 Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Thu, 12 Feb 2026 13:12:07 +0000 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=A4=96=20refactor:=20render=20API=20r?= =?UTF-8?q?efs=20with=20linked=20type=20sections?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt a Kubernetes-style API reference layout in generated docs. - Keep Spec/Status tables focused on top-level fields. - Render referenced local types later on the same page under a dedicated section. - Link local types to same-page anchors and keep Kubernetes types linked to upstream API docs. - Regenerate all API reference pages using the updated template. --- _Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.67`_ --- docs/reference/api/codercontrolplane.md | 67 +++++--- docs/reference/api/coderprovisioner.md | 88 ++++++---- docs/reference/api/codertemplate.md | 28 ++-- docs/reference/api/coderworkspace.md | 32 ++-- docs/reference/api/coderworkspaceproxy.md | 83 ++++++---- .../templates/markdown/gv_list.tpl | 153 ++++++++++++------ 6 files changed, 286 insertions(+), 165 deletions(-) diff --git a/docs/reference/api/codercontrolplane.md b/docs/reference/api/codercontrolplane.md index 2b3d1434..d13286bb 100644 --- a/docs/reference/api/codercontrolplane.md +++ b/docs/reference/api/codercontrolplane.md @@ -13,33 +13,56 @@ | Field | Type | Description | | --- | --- | --- | -| `image` | `string` | Image is the container image used for the Coder control plane pod. | -| `replicas` | `int32` | Replicas is the desired number of control plane pods. | -| `service` | `ServiceSpec` | Service controls the service created in front of the control plane. | -| ├─ `type` | `corev1.ServiceType` | Type controls the Kubernetes service type. | -| ├─ `port` | `int32` | Port controls the exposed service port. | -| └─ `annotations` | `map[string]string` | Annotations are applied to the reconciled service object. | -| `extraArgs` | `[]string` | ExtraArgs are appended to the default Coder server arguments. | -| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the Coder control plane container. | -| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. | -| └─ `name` | `string` | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) | -| `operatorAccess` | `OperatorAccessSpec` | OperatorAccess configures bootstrap API access to the coderd instance. | -| ├─ `disabled` | `bool` | Disabled turns off creation and management of the `coder-k8s-operator` user and API token. | -| └─ `generatedTokenSecretName` | `string` | GeneratedTokenSecretName stores the generated operator API token. | + +| `image` | string | Image is the container image used for the Coder control plane pod. | +| `replicas` | integer | Replicas is the desired number of control plane pods. | +| `service` | [ServiceSpec](#servicespec) | Service controls the service created in front of the control plane. | +| `extraArgs` | string array | ExtraArgs are appended to the default Coder server arguments. | +| `extraEnv` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#envvar-v1-core) array | ExtraEnv are injected into the Coder control plane container. | +| `imagePullSecrets` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array | ImagePullSecrets are used by the pod to pull private images. | +| `operatorAccess` | [OperatorAccessSpec](#operatoraccessspec) | OperatorAccess configures bootstrap API access to the coderd instance. | ## Status | Field | Type | Description | | --- | --- | --- | -| `observedGeneration` | `int64` | ObservedGeneration tracks the spec generation this status reflects. | -| `readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. | -| `url` | `string` | URL is the in-cluster URL for the control plane service. | -| `operatorTokenSecretRef` | `SecretKeySelector` | OperatorTokenSecretRef points to the Secret key containing the `coder-k8s-operator` API token. | -| ├─ `name` | `string` | Name is the Kubernetes Secret name. | -| └─ `key` | `string` | Key is the key inside the Secret data map. | -| `operatorAccessReady` | `bool` | OperatorAccessReady reports whether operator API access bootstrap succeeded. | -| `phase` | `string` | Phase is a high-level readiness indicator. | -| `conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. | + +| `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. | +| `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. | +| `url` | string | URL is the in-cluster URL for the control plane service. | +| `operatorTokenSecretRef` | [SecretKeySelector](#secretkeyselector) | OperatorTokenSecretRef points to the Secret key containing the `coder-k8s-operator` API token. | +| `operatorAccessReady` | boolean | OperatorAccessReady reports whether operator API access bootstrap succeeded. | +| `phase` | string | Phase is a high-level readiness indicator. | +| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array | Conditions are Kubernetes-standard conditions for this resource. | + + +## Referenced types +### OperatorAccessSpec +OperatorAccessSpec configures the controller-managed coderd operator user. +| Field | Type | Description | +| --- | --- | --- | + +| `disabled` | boolean | Disabled turns off creation and management of the `coder-k8s-operator`
user and API token. | +| `generatedTokenSecretName` | string | GeneratedTokenSecretName stores the generated operator API token. | + +### SecretKeySelector +SecretKeySelector identifies a key in a Secret. +| Field | Type | Description | +| --- | --- | --- | + +| `name` | string | Name is the Kubernetes Secret name. | +| `key` | string | Key is the key inside the Secret data map. | + +### ServiceSpec +ServiceSpec defines the Service configuration reconciled by the operator. +| Field | Type | Description | +| --- | --- | --- | + +| `type` | [ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#servicetype-v1-core) | Type controls the Kubernetes service type. | +| `port` | integer | Port controls the exposed service port. | +| `annotations` | object (keys:string, values:string) | Annotations are applied to the reconciled service object. | + + ## Source diff --git a/docs/reference/api/coderprovisioner.md b/docs/reference/api/coderprovisioner.md index 5c7a2d8d..f628ea07 100644 --- a/docs/reference/api/coderprovisioner.md +++ b/docs/reference/api/coderprovisioner.md @@ -13,45 +13,65 @@ | Field | Type | Description | | --- | --- | --- | -| `controlPlaneRef` | `corev1.LocalObjectReference` | ControlPlaneRef identifies which CoderControlPlane instance to join. | -| └─ `name` | `string` | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) | -| `organizationName` | `string` | OrganizationName is the Coder organization. Defaults to "default". | -| `bootstrap` | `CoderProvisionerBootstrapSpec` | Bootstrap configures credentials for provisioner key management. | -| └─ `credentialsSecretRef` | `SecretKeySelector` | CredentialsSecretRef points to a Secret containing a Coder session token with permission to manage provisioner keys. | -|    ├─ `name` | `string` | Name is the Kubernetes Secret name. | -|    └─ `key` | `string` | Key is the key inside the Secret data map. | -| `key` | `CoderProvisionerKeySpec` | Key configures provisioner key naming and secret storage. | -| ├─ `name` | `string` | Name is the provisioner key name in coderd. Defaults to the CR name. | -| ├─ `secretName` | `string` | SecretName is the Kubernetes Secret to store the key. Defaults to "\{crName\}-provisioner-key". | -| └─ `secretKey` | `string` | SecretKey is the data key in the Secret. Defaults to "key". | -| `replicas` | `int32` | Replicas is the desired number of provisioner pods. | -| `tags` | `map[string]string` | Tags are attached to the provisioner key for job routing. | -| `image` | `string` | Image is the container image. Defaults to the control plane image. | -| `extraArgs` | `[]string` | ExtraArgs are appended after "provisionerd start". | -| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the provisioner container. | -| `resources` | `corev1.ResourceRequirements` | Resources for the provisioner container. | -| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. | -| └─ `name` | `string` | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) | -| `terminationGracePeriodSeconds` | `int64` | TerminationGracePeriodSeconds for the provisioner pods. | + +| `controlPlaneRef` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | ControlPlaneRef identifies which CoderControlPlane instance to join. | +| `organizationName` | string | OrganizationName is the Coder organization. Defaults to "default". | +| `bootstrap` | [CoderProvisionerBootstrapSpec](#coderprovisionerbootstrapspec) | Bootstrap configures credentials for provisioner key management. | +| `key` | [CoderProvisionerKeySpec](#coderprovisionerkeyspec) | Key configures provisioner key naming and secret storage. | +| `replicas` | integer | Replicas is the desired number of provisioner pods. | +| `tags` | object (keys:string, values:string) | Tags are attached to the provisioner key for job routing. | +| `image` | string | Image is the container image. Defaults to the control plane image. | +| `extraArgs` | string array | ExtraArgs are appended after "provisionerd start". | +| `extraEnv` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#envvar-v1-core) array | ExtraEnv are injected into the provisioner container. | +| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#resourcerequirements-v1-core) | Resources for the provisioner container. | +| `imagePullSecrets` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array | ImagePullSecrets are used by the pod to pull private images. | +| `terminationGracePeriodSeconds` | integer | TerminationGracePeriodSeconds for the provisioner pods. | ## Status | Field | Type | Description | | --- | --- | --- | -| `observedGeneration` | `int64` | ObservedGeneration tracks the spec generation this status reflects. | -| `readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. | -| `phase` | `string` | Phase is a high-level readiness indicator. | -| `conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. | -| `organizationID` | `string` | OrganizationID is the organization ID last applied to the provisioner key. | -| `organizationName` | `string` | OrganizationName is the organization name last applied to the provisioner key. | -| `provisionerKeyID` | `string` | ProvisionerKeyID is the provisioner key ID last applied in coderd. | -| `provisionerKeyName` | `string` | ProvisionerKeyName is the provisioner key name last applied in coderd. | -| `tagsHash` | `string` | TagsHash is a deterministic hash of spec.tags last applied to the provisioner key. | -| `controlPlaneRefName` | `string` | ControlPlaneRefName is the control plane ref name last applied to the provisioner key. | -| `controlPlaneURL` | `string` | ControlPlaneURL is the control plane URL last applied to the provisioner key. | -| `secretRef` | `SecretKeySelector` | SecretRef references the provisioner key secret data currently in use. | -| ├─ `name` | `string` | Name is the Kubernetes Secret name. | -| └─ `key` | `string` | Key is the key inside the Secret data map. | + +| `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. | +| `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. | +| `phase` | string | Phase is a high-level readiness indicator. | +| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array | Conditions are Kubernetes-standard conditions for this resource. | +| `organizationID` | string | OrganizationID is the organization ID last applied to the provisioner key. | +| `organizationName` | string | OrganizationName is the organization name last applied to the provisioner key. | +| `provisionerKeyID` | string | ProvisionerKeyID is the provisioner key ID last applied in coderd. | +| `provisionerKeyName` | string | ProvisionerKeyName is the provisioner key name last applied in coderd. | +| `tagsHash` | string | TagsHash is a deterministic hash of spec.tags last applied to the provisioner key. | +| `controlPlaneRefName` | string | ControlPlaneRefName is the control plane ref name last applied to the provisioner key. | +| `controlPlaneURL` | string | ControlPlaneURL is the control plane URL last applied to the provisioner key. | +| `secretRef` | [SecretKeySelector](#secretkeyselector) | SecretRef references the provisioner key secret data currently in use. | + + +## Referenced types +### CoderProvisionerBootstrapSpec +CoderProvisionerBootstrapSpec configures credentials for provisioner key management. +| Field | Type | Description | +| --- | --- | --- | + +| `credentialsSecretRef` | [SecretKeySelector](#secretkeyselector) | CredentialsSecretRef points to a Secret containing a Coder session token
with permission to manage provisioner keys. | + +### CoderProvisionerKeySpec +CoderProvisionerKeySpec configures provisioner key naming and storage. +| Field | Type | Description | +| --- | --- | --- | + +| `name` | string | Name is the provisioner key name in coderd. Defaults to the CR name. | +| `secretName` | string | SecretName is the Kubernetes Secret to store the key. Defaults to "\{crName\}-provisioner-key". | +| `secretKey` | string | SecretKey is the data key in the Secret. Defaults to "key". | + +### SecretKeySelector +SecretKeySelector identifies a key in a Secret. +| Field | Type | Description | +| --- | --- | --- | + +| `name` | string | Name is the Kubernetes Secret name. | +| `key` | string | Key is the key inside the Secret data map. | + + ## Source diff --git a/docs/reference/api/codertemplate.md b/docs/reference/api/codertemplate.md index 1760ca02..f565f875 100644 --- a/docs/reference/api/codertemplate.md +++ b/docs/reference/api/codertemplate.md @@ -13,23 +13,27 @@ | Field | Type | Description | | --- | --- | --- | -| `organization` | `string` | Organization is the Coder organization name (must match the organization prefix in metadata.name). | -| `versionID` | `string` | VersionID is the Coder template version UUID used on creation (required for CREATE). | -| `displayName` | `string` | | -| `description` | `string` | | -| `icon` | `string` | | -| `running` | `bool` | Running is a legacy flag retained temporarily for in-repo callers that still read template run-state directly. | + +| `organization` | string | Organization is the Coder organization name (must match the organization prefix in metadata.name). | +| `versionID` | string | VersionID is the Coder template version UUID used on creation (required for CREATE). | +| `displayName` | string | | +| `description` | string | | +| `icon` | string | | +| `running` | boolean | Running is a legacy flag retained temporarily for in-repo callers that still read template run-state directly. | ## Status | Field | Type | Description | | --- | --- | --- | -| `id` | `string` | | -| `organizationName` | `string` | | -| `activeVersionID` | `string` | | -| `deprecated` | `bool` | | -| `updatedAt` | `metav1.Time` | | -| `autoShutdown` | `metav1.Time` | AutoShutdown is a legacy timestamp retained temporarily for in-repo callers that still surface template shutdown timestamps. | + +| `id` | string | | +| `organizationName` | string | | +| `activeVersionID` | string | | +| `deprecated` | boolean | | +| `updatedAt` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | | +| `autoShutdown` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | AutoShutdown is a legacy timestamp retained temporarily for in-repo callers that still surface template shutdown timestamps. | + + ## Source diff --git a/docs/reference/api/coderworkspace.md b/docs/reference/api/coderworkspace.md index 3ffff79a..0e4e5f0b 100644 --- a/docs/reference/api/coderworkspace.md +++ b/docs/reference/api/coderworkspace.md @@ -13,25 +13,29 @@ | Field | Type | Description | | --- | --- | --- | -| `organization` | `string` | Organization is the Coder organization name. | -| `templateName` | `string` | TemplateName resolves via TemplateByName(organization, templateName). | -| `templateVersionID` | `string` | TemplateVersionID optionally pins to a specific template version. | -| `running` | `bool` | Running drives start/stop via CreateWorkspaceBuild. | -| `ttlMillis` | `int64` | | -| `autostartSchedule` | `string` | | + +| `organization` | string | Organization is the Coder organization name. | +| `templateName` | string | TemplateName resolves via TemplateByName(organization, templateName). | +| `templateVersionID` | string | TemplateVersionID optionally pins to a specific template version. | +| `running` | boolean | Running drives start/stop via CreateWorkspaceBuild. | +| `ttlMillis` | integer | | +| `autostartSchedule` | string | | ## Status | Field | Type | Description | | --- | --- | --- | -| `id` | `string` | | -| `ownerName` | `string` | | -| `organizationName` | `string` | | -| `templateName` | `string` | | -| `latestBuildID` | `string` | | -| `latestBuildStatus` | `string` | | -| `autoShutdown` | `metav1.Time` | | -| `lastUsedAt` | `metav1.Time` | | + +| `id` | string | | +| `ownerName` | string | | +| `organizationName` | string | | +| `templateName` | string | | +| `latestBuildID` | string | | +| `latestBuildStatus` | string | | +| `autoShutdown` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | | +| `lastUsedAt` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | | + + ## Source diff --git a/docs/reference/api/coderworkspaceproxy.md b/docs/reference/api/coderworkspaceproxy.md index 5ddc9a88..98692b3c 100644 --- a/docs/reference/api/coderworkspaceproxy.md +++ b/docs/reference/api/coderworkspaceproxy.md @@ -13,43 +13,62 @@ | Field | Type | Description | | --- | --- | --- | -| `image` | `string` | Image is the container image used for the workspace proxy pod. | -| `replicas` | `int32` | Replicas is the desired number of proxy pods. | -| `service` | `ServiceSpec` | Service controls the service created in front of the workspace proxy. | -| ├─ `type` | `corev1.ServiceType` | Type controls the Kubernetes service type. | -| ├─ `port` | `int32` | Port controls the exposed service port. | -| └─ `annotations` | `map[string]string` | Annotations are applied to the reconciled service object. | -| `primaryAccessURL` | `string` | PrimaryAccessURL is the coderd URL the proxy should connect to. | -| `proxySessionTokenSecretRef` | `SecretKeySelector` | ProxySessionTokenSecretRef points to a Secret key containing the proxy token. | -| ├─ `name` | `string` | Name is the Kubernetes Secret name. | -| └─ `key` | `string` | Key is the key inside the Secret data map. | -| `bootstrap` | `ProxyBootstrapSpec` | Bootstrap optionally registers the proxy and mints a proxy token. | -| ├─ `coderURL` | `string` | CoderURL is the URL for the primary Coder control plane API. | -| ├─ `credentialsSecretRef` | `SecretKeySelector` | CredentialsSecretRef points to a Secret containing a Coder session token. | -| │  ├─ `name` | `string` | Name is the Kubernetes Secret name. | -| │  └─ `key` | `string` | Key is the key inside the Secret data map. | -| ├─ `proxyName` | `string` | ProxyName is the name used when registering the proxy in Coder. | -| ├─ `displayName` | `string` | DisplayName is the human-readable name for the proxy region. | -| ├─ `icon` | `string` | Icon is the optional icon URL or emoji path for the proxy region. | -| └─ `generatedTokenSecretName` | `string` | GeneratedTokenSecretName stores the generated proxy token. | -| `derpOnly` | `bool` | DerpOnly configures the workspace proxy to only serve DERP traffic. | -| `extraArgs` | `[]string` | ExtraArgs are appended to the default workspace proxy arguments. | -| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the workspace proxy container. | -| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. | -| └─ `name` | `string` | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) | + +| `image` | string | Image is the container image used for the workspace proxy pod. | +| `replicas` | integer | Replicas is the desired number of proxy pods. | +| `service` | [ServiceSpec](#servicespec) | Service controls the service created in front of the workspace proxy. | +| `primaryAccessURL` | string | PrimaryAccessURL is the coderd URL the proxy should connect to. | +| `proxySessionTokenSecretRef` | [SecretKeySelector](#secretkeyselector) | ProxySessionTokenSecretRef points to a Secret key containing the proxy token. | +| `bootstrap` | [ProxyBootstrapSpec](#proxybootstrapspec) | Bootstrap optionally registers the proxy and mints a proxy token. | +| `derpOnly` | boolean | DerpOnly configures the workspace proxy to only serve DERP traffic. | +| `extraArgs` | string array | ExtraArgs are appended to the default workspace proxy arguments. | +| `extraEnv` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#envvar-v1-core) array | ExtraEnv are injected into the workspace proxy container. | +| `imagePullSecrets` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array | ImagePullSecrets are used by the pod to pull private images. | ## Status | Field | Type | Description | | --- | --- | --- | -| `observedGeneration` | `int64` | ObservedGeneration tracks the spec generation this status reflects. | -| `readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. | -| `registered` | `bool` | Registered reports whether bootstrap registration completed successfully. | -| `proxyTokenSecretRef` | `SecretKeySelector` | ProxyTokenSecretRef is the Secret used for the proxy session token. | -| ├─ `name` | `string` | Name is the Kubernetes Secret name. | -| └─ `key` | `string` | Key is the key inside the Secret data map. | -| `phase` | `string` | Phase is a high-level readiness indicator. | -| `conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. | + +| `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. | +| `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. | +| `registered` | boolean | Registered reports whether bootstrap registration completed successfully. | +| `proxyTokenSecretRef` | [SecretKeySelector](#secretkeyselector) | ProxyTokenSecretRef is the Secret used for the proxy session token. | +| `phase` | string | Phase is a high-level readiness indicator. | +| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array | Conditions are Kubernetes-standard conditions for this resource. | + + +## Referenced types +### ProxyBootstrapSpec +ProxyBootstrapSpec configures optional registration with the Coder API. +| Field | Type | Description | +| --- | --- | --- | + +| `coderURL` | string | CoderURL is the URL for the primary Coder control plane API. | +| `credentialsSecretRef` | [SecretKeySelector](#secretkeyselector) | CredentialsSecretRef points to a Secret containing a Coder session token. | +| `proxyName` | string | ProxyName is the name used when registering the proxy in Coder. | +| `displayName` | string | DisplayName is the human-readable name for the proxy region. | +| `icon` | string | Icon is the optional icon URL or emoji path for the proxy region. | +| `generatedTokenSecretName` | string | GeneratedTokenSecretName stores the generated proxy token. | + +### SecretKeySelector +SecretKeySelector identifies a key in a Secret. +| Field | Type | Description | +| --- | --- | --- | + +| `name` | string | Name is the Kubernetes Secret name. | +| `key` | string | Key is the key inside the Secret data map. | + +### ServiceSpec +ServiceSpec defines the Service configuration reconciled by the operator. +| Field | Type | Description | +| --- | --- | --- | + +| `type` | [ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#servicetype-v1-core) | Type controls the Kubernetes service type. | +| `port` | integer | Port controls the exposed service port. | +| `annotations` | object (keys:string, values:string) | Annotations are applied to the reconciled service object. | + + ## Source diff --git a/hack/crd-ref-docs/templates/markdown/gv_list.tpl b/hack/crd-ref-docs/templates/markdown/gv_list.tpl index 29c4578e..0defc973 100644 --- a/hack/crd-ref-docs/templates/markdown/gv_list.tpl +++ b/hack/crd-ref-docs/templates/markdown/gv_list.tpl @@ -1,58 +1,87 @@ -{{- define "typeName" -}} -{{- $fieldType := . -}} -{{- if not $fieldType -}} - +{{- define "fieldDoc" -}} +{{- $doc := . -}} +{{- if not $doc -}} +{{- "" -}} {{- else -}} -{{- $typeString := $fieldType.String -}} -{{- $typeString = trimPrefix "*" $typeString -}} -{{- $typeString = $typeString | replace "k8s.io/apimachinery/pkg/apis/meta/v1." "metav1." -}} -{{- $typeString = $typeString | replace "k8s.io/api/core/v1." "corev1." -}} -{{- $typeString = $typeString | replace "github.com/coder/coder-k8s/api/v1alpha1." "" -}} -{{- $typeString = $typeString | replace "github.com/coder/coder-k8s/api/aggregation/v1alpha1." "" -}} -{{- $typeString -}} -{{- end -}} -{{- end -}} - -{{- define "renderFields" -}} -{{- $fields := .fields -}} -{{- $depth := int .depth -}} -{{- $maxDepth := int .maxDepth -}} -{{- $treePrefix := .treePrefix -}} -{{- $fieldCount := len $fields -}} -{{- range $index, $field := $fields }} +{{- $rendered := markdownRenderFieldDoc $doc -}} +{{- $rendered = regexReplaceAll "(https?://[^[:space:]<]+)" $rendered "[$1]($1)" -}} +{{- $rendered -}} +{{- end -}} +{{- end -}} + +{{- define "renderFieldsTableRows" -}} +{{- $fields := . -}} +{{- range $field := $fields }} {{- if not $field.Type }}{{ fail (printf "field %q is missing type information" $field.Name) }}{{- end }} -{{- $memberType := $field.Type -}} -{{- $members := $memberType.Members -}} -{{- $hasMembers := gt (len $members) 0 -}} -{{- $memberTypeString := $memberType.String -}} -{{- $isProjectLocal := contains "github.com/coder/coder-k8s/api/" $memberTypeString -}} -{{- $isLocalObjectRef := contains "k8s.io/api/core/v1.LocalObjectReference" $memberTypeString -}} -{{- $shouldExpand := and $hasMembers (lt $depth $maxDepth) (or $isProjectLocal $isLocalObjectRef) -}} -{{- $isLast := eq (add $index 1) $fieldCount -}} -{{- $branch := "" -}} -{{- if gt $depth 0 -}} -{{- if $isLast -}} -{{- $branch = "└─ " -}} -{{- else -}} -{{- $branch = "├─ " -}} +| `{{ $field.Name }}` | {{ markdownRenderType $field.Type }} | {{ template "fieldDoc" $field.Doc }} | {{- end -}} {{- end -}} -{{- $fieldDoc := markdownRenderFieldDoc $field.Doc -}} -{{- $fieldDoc = $fieldDoc | replace "
" " " -}} -{{- $fieldDoc = regexReplaceAll "(https?://[^[:space:]<]+)" $fieldDoc "[$1]($1)" -}} -| {{ $treePrefix }}{{ $branch }}`{{ $field.Name }}` | `{{ template "typeName" $memberType }}` | {{ $fieldDoc }} | -{{ $childPrefix := $treePrefix -}} -{{- if gt $depth 0 -}} -{{- if $isLast -}} -{{- $childPrefix = printf "%s   " $treePrefix -}} -{{- else -}} -{{- $childPrefix = printf "%s│  " $treePrefix -}} + +{{- define "collectReferencedTypes" -}} +{{- $type := .type -}} +{{- if not $type -}} +{{- fail "assertion failed: collectReferencedTypes requires type" -}} +{{- end -}} +{{- $refs := .refs -}} +{{- $visited := .visited -}} + +{{- $uid := $type.UID -}} +{{- if eq $uid "" -}} +{{- $uid = $type.String -}} +{{- end -}} +{{- if not (hasKey $visited $uid) -}} +{{- $_ := set $visited $uid true -}} + +{{- $members := $type.Members -}} +{{- $typePackage := $type.Package -}} +{{- $isProjectLocal := or (hasPrefix "github.com/coder/coder-k8s/api/v1alpha1" $typePackage) (hasPrefix "github.com/coder/coder-k8s/api/aggregation/v1alpha1" $typePackage) -}} +{{- if and $isProjectLocal (or (gt (len $members) 0) (gt (len $type.EnumValues) 0)) -}} +{{- $typeKey := printf "%s.%s" $type.Package $type.Name -}} +{{- $_ := set $refs $typeKey $type -}} +{{- end -}} + +{{- if $type.UnderlyingType -}} +{{- template "collectReferencedTypes" (dict "type" $type.UnderlyingType "refs" $refs "visited" $visited) -}} +{{- end -}} +{{- if $type.KeyType -}} +{{- template "collectReferencedTypes" (dict "type" $type.KeyType "refs" $refs "visited" $visited) -}} +{{- end -}} +{{- if $type.ValueType -}} +{{- template "collectReferencedTypes" (dict "type" $type.ValueType "refs" $refs "visited" $visited) -}} +{{- end -}} +{{- range $field := $members -}} +{{- if not $field.Type }}{{ fail (printf "field %q is missing type information" $field.Name) }}{{- end -}} +{{- template "collectReferencedTypes" (dict "type" $field.Type "refs" $refs "visited" $visited) -}} {{- end -}} -{{- else -}} -{{- $childPrefix = "" -}} {{- end -}} -{{ if $shouldExpand }}{{ template "renderFields" (dict "fields" $members "depth" (add $depth 1) "maxDepth" $maxDepth "treePrefix" $childPrefix) }}{{ end }} {{- end -}} + +{{- define "renderTypeDefinition" -}} +{{- $type := . -}} +{{- if not $type -}} +{{- fail "assertion failed: renderTypeDefinition requires type" -}} +{{- end }} +### {{ $type.Name }} + +{{- $typeDoc := trim $type.Doc -}} +{{- if ne $typeDoc "" }} +{{ regexReplaceAll "(https?://[^[:space:]<]+)" $typeDoc "[$1]($1)" }} + +{{- end }} +{{- if gt (len $type.Members) 0 }} +| Field | Type | Description | +| --- | --- | --- | +{{ template "renderFieldsTableRows" $type.Members }} + +{{- end }} +{{- if gt (len $type.EnumValues) 0 }} +| Value | Description | +| --- | --- | +{{- range $value := $type.EnumValues }} +| `{{ $value.Name }}` | {{ template "fieldDoc" $value.Doc }} | +{{- end }} + +{{- end }} {{- end -}} {{- define "gvList" -}} @@ -106,7 +135,18 @@ {{- if eq (len $statusMembers) 0 -}} {{ fail (printf "expected kind %q to contain at least one status field" $kind) }} {{- end -}} -{{- $maxFieldDepth := 3 -}} + +{{- $referencedTypes := dict -}} +{{- $visitedTypes := dict -}} +{{- range $field := $specMembers -}} +{{- if not $field.Type }}{{ fail (printf "field %q is missing type information" $field.Name) }}{{- end -}} +{{- template "collectReferencedTypes" (dict "type" $field.Type "refs" $referencedTypes "visited" $visitedTypes) -}} +{{- end -}} +{{- range $field := $statusMembers -}} +{{- if not $field.Type }}{{ fail (printf "field %q is missing type information" $field.Name) }}{{- end -}} +{{- template "collectReferencedTypes" (dict "type" $field.Type "refs" $referencedTypes "visited" $visitedTypes) -}} +{{- end -}} +{{- $referencedTypeKeys := keys $referencedTypes | sortAlpha -}} @@ -123,12 +163,23 @@ | Field | Type | Description | | --- | --- | --- | -{{ template "renderFields" (dict "fields" $specMembers "depth" 0 "maxDepth" $maxFieldDepth "treePrefix" "") }} +{{ template "renderFieldsTableRows" $specMembers }} + ## Status | Field | Type | Description | | --- | --- | --- | -{{ template "renderFields" (dict "fields" $statusMembers "depth" 0 "maxDepth" $maxFieldDepth "treePrefix" "") }} +{{ template "renderFieldsTableRows" $statusMembers }} + +{{ if gt (len $referencedTypeKeys) 0 }} +## Referenced types + +{{- range $typeKey := $referencedTypeKeys }} +{{- $type := index $referencedTypes $typeKey -}} +{{ template "renderTypeDefinition" $type }} +{{ end }} +{{ end }} + ## Source - Go type: `{{ $goType }}` From 38b09c904922028f5e72e630c6cd5a494839f3df Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Thu, 12 Feb 2026 13:25:57 +0000 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=A4=96=20fix:=20normalize=20generated?= =?UTF-8?q?=20API=20reference=20markdown=20output?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address docs-quality CI failures from markdownlint by tightening generated Markdown output. - Refined the API reference template row/type rendering to reduce malformed line merges. - Added post-generation blank-line normalization in `hack/update-reference-docs.sh`. - Regenerated API reference docs and verified markdownlint/cspell cleanliness. --- _Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.67`_ --- docs/reference/api/codercontrolplane.md | 17 ++++----- docs/reference/api/coderprovisioner.md | 17 ++++----- docs/reference/api/codertemplate.md | 4 -- docs/reference/api/coderworkspace.md | 4 -- docs/reference/api/coderworkspaceproxy.md | 15 ++++---- .../templates/markdown/gv_list.tpl | 37 ++++++++++--------- hack/update-reference-docs.sh | 32 ++++++++++++++++ 7 files changed, 75 insertions(+), 51 deletions(-) diff --git a/docs/reference/api/codercontrolplane.md b/docs/reference/api/codercontrolplane.md index d13286bb..fe27ca36 100644 --- a/docs/reference/api/codercontrolplane.md +++ b/docs/reference/api/codercontrolplane.md @@ -13,7 +13,6 @@ | Field | Type | Description | | --- | --- | --- | - | `image` | string | Image is the container image used for the Coder control plane pod. | | `replicas` | integer | Replicas is the desired number of control plane pods. | | `service` | [ServiceSpec](#servicespec) | Service controls the service created in front of the control plane. | @@ -26,7 +25,6 @@ | Field | Type | Description | | --- | --- | --- | - | `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. | | `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. | | `url` | string | URL is the in-cluster URL for the control plane service. | @@ -35,35 +33,36 @@ | `phase` | string | Phase is a high-level readiness indicator. | | `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array | Conditions are Kubernetes-standard conditions for this resource. | - ## Referenced types + ### OperatorAccessSpec + OperatorAccessSpec configures the controller-managed coderd operator user. + | Field | Type | Description | | --- | --- | --- | - -| `disabled` | boolean | Disabled turns off creation and management of the `coder-k8s-operator`
user and API token. | +| `disabled` | boolean | Disabled turns off creation and management of the `coder-k8s-operator` user and API token. | | `generatedTokenSecretName` | string | GeneratedTokenSecretName stores the generated operator API token. | ### SecretKeySelector + SecretKeySelector identifies a key in a Secret. + | Field | Type | Description | | --- | --- | --- | - | `name` | string | Name is the Kubernetes Secret name. | | `key` | string | Key is the key inside the Secret data map. | ### ServiceSpec + ServiceSpec defines the Service configuration reconciled by the operator. + | Field | Type | Description | | --- | --- | --- | - | `type` | [ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#servicetype-v1-core) | Type controls the Kubernetes service type. | | `port` | integer | Port controls the exposed service port. | | `annotations` | object (keys:string, values:string) | Annotations are applied to the reconciled service object. | - - ## Source - Go type: `api/v1alpha1/codercontrolplane_types.go` diff --git a/docs/reference/api/coderprovisioner.md b/docs/reference/api/coderprovisioner.md index f628ea07..085a41f8 100644 --- a/docs/reference/api/coderprovisioner.md +++ b/docs/reference/api/coderprovisioner.md @@ -13,7 +13,6 @@ | Field | Type | Description | | --- | --- | --- | - | `controlPlaneRef` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | ControlPlaneRef identifies which CoderControlPlane instance to join. | | `organizationName` | string | OrganizationName is the Coder organization. Defaults to "default". | | `bootstrap` | [CoderProvisionerBootstrapSpec](#coderprovisionerbootstrapspec) | Bootstrap configures credentials for provisioner key management. | @@ -31,7 +30,6 @@ | Field | Type | Description | | --- | --- | --- | - | `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. | | `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. | | `phase` | string | Phase is a high-level readiness indicator. | @@ -45,34 +43,35 @@ | `controlPlaneURL` | string | ControlPlaneURL is the control plane URL last applied to the provisioner key. | | `secretRef` | [SecretKeySelector](#secretkeyselector) | SecretRef references the provisioner key secret data currently in use. | - ## Referenced types + ### CoderProvisionerBootstrapSpec + CoderProvisionerBootstrapSpec configures credentials for provisioner key management. + | Field | Type | Description | | --- | --- | --- | - -| `credentialsSecretRef` | [SecretKeySelector](#secretkeyselector) | CredentialsSecretRef points to a Secret containing a Coder session token
with permission to manage provisioner keys. | +| `credentialsSecretRef` | [SecretKeySelector](#secretkeyselector) | CredentialsSecretRef points to a Secret containing a Coder session token with permission to manage provisioner keys. | ### CoderProvisionerKeySpec + CoderProvisionerKeySpec configures provisioner key naming and storage. + | Field | Type | Description | | --- | --- | --- | - | `name` | string | Name is the provisioner key name in coderd. Defaults to the CR name. | | `secretName` | string | SecretName is the Kubernetes Secret to store the key. Defaults to "\{crName\}-provisioner-key". | | `secretKey` | string | SecretKey is the data key in the Secret. Defaults to "key". | ### SecretKeySelector + SecretKeySelector identifies a key in a Secret. + | Field | Type | Description | | --- | --- | --- | - | `name` | string | Name is the Kubernetes Secret name. | | `key` | string | Key is the key inside the Secret data map. | - - ## Source - Go type: `api/v1alpha1/coderprovisioner_types.go` diff --git a/docs/reference/api/codertemplate.md b/docs/reference/api/codertemplate.md index f565f875..c1ed0af6 100644 --- a/docs/reference/api/codertemplate.md +++ b/docs/reference/api/codertemplate.md @@ -13,7 +13,6 @@ | Field | Type | Description | | --- | --- | --- | - | `organization` | string | Organization is the Coder organization name (must match the organization prefix in metadata.name). | | `versionID` | string | VersionID is the Coder template version UUID used on creation (required for CREATE). | | `displayName` | string | | @@ -25,7 +24,6 @@ | Field | Type | Description | | --- | --- | --- | - | `id` | string | | | `organizationName` | string | | | `activeVersionID` | string | | @@ -33,8 +31,6 @@ | `updatedAt` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | | | `autoShutdown` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | AutoShutdown is a legacy timestamp retained temporarily for in-repo callers that still surface template shutdown timestamps. | - - ## Source - Go type: `api/aggregation/v1alpha1/types.go` diff --git a/docs/reference/api/coderworkspace.md b/docs/reference/api/coderworkspace.md index 0e4e5f0b..da8b10a4 100644 --- a/docs/reference/api/coderworkspace.md +++ b/docs/reference/api/coderworkspace.md @@ -13,7 +13,6 @@ | Field | Type | Description | | --- | --- | --- | - | `organization` | string | Organization is the Coder organization name. | | `templateName` | string | TemplateName resolves via TemplateByName(organization, templateName). | | `templateVersionID` | string | TemplateVersionID optionally pins to a specific template version. | @@ -25,7 +24,6 @@ | Field | Type | Description | | --- | --- | --- | - | `id` | string | | | `ownerName` | string | | | `organizationName` | string | | @@ -35,8 +33,6 @@ | `autoShutdown` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | | | `lastUsedAt` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | | - - ## Source - Go type: `api/aggregation/v1alpha1/types.go` diff --git a/docs/reference/api/coderworkspaceproxy.md b/docs/reference/api/coderworkspaceproxy.md index 98692b3c..b034d1b1 100644 --- a/docs/reference/api/coderworkspaceproxy.md +++ b/docs/reference/api/coderworkspaceproxy.md @@ -13,7 +13,6 @@ | Field | Type | Description | | --- | --- | --- | - | `image` | string | Image is the container image used for the workspace proxy pod. | | `replicas` | integer | Replicas is the desired number of proxy pods. | | `service` | [ServiceSpec](#servicespec) | Service controls the service created in front of the workspace proxy. | @@ -29,7 +28,6 @@ | Field | Type | Description | | --- | --- | --- | - | `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. | | `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. | | `registered` | boolean | Registered reports whether bootstrap registration completed successfully. | @@ -37,13 +35,14 @@ | `phase` | string | Phase is a high-level readiness indicator. | | `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array | Conditions are Kubernetes-standard conditions for this resource. | - ## Referenced types + ### ProxyBootstrapSpec + ProxyBootstrapSpec configures optional registration with the Coder API. + | Field | Type | Description | | --- | --- | --- | - | `coderURL` | string | CoderURL is the URL for the primary Coder control plane API. | | `credentialsSecretRef` | [SecretKeySelector](#secretkeyselector) | CredentialsSecretRef points to a Secret containing a Coder session token. | | `proxyName` | string | ProxyName is the name used when registering the proxy in Coder. | @@ -52,24 +51,24 @@ ProxyBootstrapSpec configures optional registration with the Coder API. | `generatedTokenSecretName` | string | GeneratedTokenSecretName stores the generated proxy token. | ### SecretKeySelector + SecretKeySelector identifies a key in a Secret. + | Field | Type | Description | | --- | --- | --- | - | `name` | string | Name is the Kubernetes Secret name. | | `key` | string | Key is the key inside the Secret data map. | ### ServiceSpec + ServiceSpec defines the Service configuration reconciled by the operator. + | Field | Type | Description | | --- | --- | --- | - | `type` | [ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#servicetype-v1-core) | Type controls the Kubernetes service type. | | `port` | integer | Port controls the exposed service port. | | `annotations` | object (keys:string, values:string) | Annotations are applied to the reconciled service object. | - - ## Source - Go type: `api/v1alpha1/coderworkspaceproxy_types.go` diff --git a/hack/crd-ref-docs/templates/markdown/gv_list.tpl b/hack/crd-ref-docs/templates/markdown/gv_list.tpl index 0defc973..1606d7c4 100644 --- a/hack/crd-ref-docs/templates/markdown/gv_list.tpl +++ b/hack/crd-ref-docs/templates/markdown/gv_list.tpl @@ -4,17 +4,20 @@ {{- "" -}} {{- else -}} {{- $rendered := markdownRenderFieldDoc $doc -}} +{{- $rendered = $rendered | replace "
" " " -}} {{- $rendered = regexReplaceAll "(https?://[^[:space:]<]+)" $rendered "[$1]($1)" -}} {{- $rendered -}} {{- end -}} {{- end -}} {{- define "renderFieldsTableRows" -}} -{{- $fields := . -}} -{{- range $field := $fields }} -{{- if not $field.Type }}{{ fail (printf "field %q is missing type information" $field.Name) }}{{- end }} -| `{{ $field.Name }}` | {{ markdownRenderType $field.Type }} | {{ template "fieldDoc" $field.Doc }} | -{{- end -}} +{{- range $field := . -}} +{{- if not $field.Type }}{{ fail (printf "field %q is missing type information" $field.Name) }}{{- end -}} +{{- $fieldDoc := markdownRenderFieldDoc $field.Doc -}} +{{- $fieldDoc = $fieldDoc | replace "
" " " -}} +{{- $fieldDoc = regexReplaceAll "(https?://[^[:space:]<]+)" $fieldDoc "[$1]($1)" -}} +| `{{ $field.Name }}` | {{ markdownRenderType $field.Type }} | {{ $fieldDoc }} | +{{ end -}} {{- end -}} {{- define "collectReferencedTypes" -}} @@ -60,28 +63,28 @@ {{- $type := . -}} {{- if not $type -}} {{- fail "assertion failed: renderTypeDefinition requires type" -}} -{{- end }} +{{- end -}} ### {{ $type.Name }} -{{- $typeDoc := trim $type.Doc -}} -{{- if ne $typeDoc "" }} +{{ $typeDoc := trim $type.Doc }} +{{ if ne $typeDoc "" }} {{ regexReplaceAll "(https?://[^[:space:]<]+)" $typeDoc "[$1]($1)" }} -{{- end }} -{{- if gt (len $type.Members) 0 }} +{{ end }} +{{ if gt (len $type.Members) 0 }} | Field | Type | Description | | --- | --- | --- | {{ template "renderFieldsTableRows" $type.Members }} -{{- end }} -{{- if gt (len $type.EnumValues) 0 }} +{{ end }} +{{ if gt (len $type.EnumValues) 0 }} | Value | Description | | --- | --- | -{{- range $value := $type.EnumValues }} +{{ range $value := $type.EnumValues }} | `{{ $value.Name }}` | {{ template "fieldDoc" $value.Doc }} | -{{- end }} +{{ end }} -{{- end }} +{{ end }} {{- end -}} {{- define "gvList" -}} @@ -174,8 +177,8 @@ {{ if gt (len $referencedTypeKeys) 0 }} ## Referenced types -{{- range $typeKey := $referencedTypeKeys }} -{{- $type := index $referencedTypes $typeKey -}} +{{ range $typeKey := $referencedTypeKeys }} +{{ $type := index $referencedTypes $typeKey }} {{ template "renderTypeDefinition" $type }} {{ end }} {{ end }} diff --git a/hack/update-reference-docs.sh b/hack/update-reference-docs.sh index 31c1b0f1..6200ef1e 100755 --- a/hack/update-reference-docs.sh +++ b/hack/update-reference-docs.sh @@ -184,6 +184,37 @@ generate_kind_doc() { "$@" } +normalize_generated_doc_spacing() { + local output_path="$1" + local full_path="${SCRIPT_ROOT}/${output_path}" + local temp_file + + assert_file "${full_path}" + + temp_file="$(mktemp)" + track_temp_file "${temp_file}" + + awk ' + BEGIN { + blank_count = 0 + } + { + if ($0 ~ /^[[:space:]]*$/) { + blank_count += 1 + if (blank_count > 1) { + next + } + print "" + next + } + blank_count = 0 + print + } + ' "${full_path}" >"${temp_file}" + + mv "${temp_file}" "${full_path}" +} + generate_docs_for_source() { local source_path="$1" local source_kind="$2" @@ -246,6 +277,7 @@ generate_docs_for_source() { esac generate_kind_doc "${source_path}" "${output_path}" "${kind}" "${template_values[@]}" + normalize_generated_doc_spacing "${output_path}" EXPECTED_GENERATED_DOCS["${output_path}"]=1 API_NAV_ENTRIES+=(" - ${kind}: reference/api/$(lower "${kind}").md") done < <(discover_root_kinds "${source_path}") From 9585e3519b29d9e6ad28091cb0fa09e3f548f4c3 Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Thu, 12 Feb 2026 13:28:40 +0000 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=A4=96=20fix:=20normalize=20generated?= =?UTF-8?q?=20API=20table=20spacing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prevent markdown table breakage by normalizing generated blank lines in API reference docs. - Keep at most one consecutive blank line globally. - Remove blank lines that appear directly after markdown table separator rows. - Preserve deterministic docs output in `make docs-reference` for CI checks. --- _Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.67`_ --- hack/update-reference-docs.sh | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/hack/update-reference-docs.sh b/hack/update-reference-docs.sh index 6200ef1e..4944efb1 100755 --- a/hack/update-reference-docs.sh +++ b/hack/update-reference-docs.sh @@ -197,9 +197,13 @@ normalize_generated_doc_spacing() { awk ' BEGIN { blank_count = 0 + prev_table_separator = 0 } { if ($0 ~ /^[[:space:]]*$/) { + if (prev_table_separator) { + next + } blank_count += 1 if (blank_count > 1) { next @@ -209,6 +213,11 @@ normalize_generated_doc_spacing() { } blank_count = 0 print + if ($0 ~ /^[[:space:]]*\|[-:|[:space:]]+\|[[:space:]]*$/) { + prev_table_separator = 1 + } else { + prev_table_separator = 0 + } } ' "${full_path}" >"${temp_file}"