Skip to content

Commit e8a597d

Browse files
ThomasK33ThomasK33
authored
🤖 fix: make nested API reference fields visually hierarchical (#62)
## Summary This PR improves generated API reference readability by rendering nested fields with explicit tree prefixes instead of invisible non-breaking-space indentation. ## Background We recently switched API docs to be more YAML-oriented, but nested structure was still hard to read in rendered markdown tables because indentation relied on `&nbsp;` in table cells. ## Implementation - Updated `hack/crd-ref-docs/templates/markdown/gv_list.tpl`: - Replaced `&nbsp;&nbsp;` indentation with tree-style prefixes (`├─`, `└─`, `│`). - Added sibling-aware branch rendering so child rows show correct continuation lines. - Regenerated affected API docs: - `docs/reference/api/codercontrolplane.md` - `docs/reference/api/coderprovisioner.md` - `docs/reference/api/workspaceproxy.md` ## Validation - `make verify-vendor` - `make test` - `make build` - `make lint` - `make docs-build` - `make docs-reference` ## Risks Low. This change only affects markdown template output and generated docs. Runtime code paths are unchanged. --- _Generated with [`mux`](https://github.com/coder/mux) • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.56`_ <!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh costs=0.56 -->
1 parent 6adb4be commit e8a597d

4 files changed

Lines changed: 60 additions & 40 deletions

File tree

‎docs/reference/api/codercontrolplane.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,16 @@
1616
| `image` | `string` | Image is the container image used for the Coder control plane pod. |
1717
| `replicas` | `int32` | Replicas is the desired number of control plane pods. |
1818
| `service` | `ServiceSpec` | Service controls the service created in front of the control plane. |
19-
| &nbsp;&nbsp;`type` | `corev1.ServiceType` | Type controls the Kubernetes service type. |
20-
| &nbsp;&nbsp;`port` | `int32` | Port controls the exposed service port. |
21-
| &nbsp;&nbsp;`annotations` | `map[string]string` | Annotations are applied to the reconciled service object. |
19+
| ├─ `type` | `corev1.ServiceType` | Type controls the Kubernetes service type. |
20+
| ├─ `port` | `int32` | Port controls the exposed service port. |
21+
| └─ `annotations` | `map[string]string` | Annotations are applied to the reconciled service object. |
2222
| `extraArgs` | `[]string` | ExtraArgs are appended to the default Coder server arguments. |
2323
| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the Coder control plane container. |
2424
| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. |
25-
| &nbsp;&nbsp;`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) |
25+
| └─ `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) |
2626
| `operatorAccess` | `OperatorAccessSpec` | OperatorAccess configures bootstrap API access to the coderd instance. |
27-
| &nbsp;&nbsp;`disabled` | `bool` | Disabled turns off creation and management of the `coder-k8s-operator` user and API token. |
28-
| &nbsp;&nbsp;`generatedTokenSecretName` | `string` | GeneratedTokenSecretName stores the generated operator API token. |
27+
| ├─ `disabled` | `bool` | Disabled turns off creation and management of the `coder-k8s-operator` user and API token. |
28+
| └─ `generatedTokenSecretName` | `string` | GeneratedTokenSecretName stores the generated operator API token. |
2929

3030
## Status
3131

@@ -35,8 +35,8 @@
3535
| `readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. |
3636
| `url` | `string` | URL is the in-cluster URL for the control plane service. |
3737
| `operatorTokenSecretRef` | `SecretKeySelector` | OperatorTokenSecretRef points to the Secret key containing the `coder-k8s-operator` API token. |
38-
| &nbsp;&nbsp;`name` | `string` | Name is the Kubernetes Secret name. |
39-
| &nbsp;&nbsp;`key` | `string` | Key is the key inside the Secret data map. |
38+
| ├─ `name` | `string` | Name is the Kubernetes Secret name. |
39+
| └─ `key` | `string` | Key is the key inside the Secret data map. |
4040
| `operatorAccessReady` | `bool` | OperatorAccessReady reports whether operator API access bootstrap succeeded. |
4141
| `phase` | `string` | Phase is a high-level readiness indicator. |
4242
| `conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. |

‎docs/reference/api/coderprovisioner.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,24 +14,24 @@
1414
| Field | Type | Description |
1515
| --- | --- | --- |
1616
| `controlPlaneRef` | `corev1.LocalObjectReference` | ControlPlaneRef identifies which CoderControlPlane instance to join. |
17-
| &nbsp;&nbsp;`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) |
17+
| └─ `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) |
1818
| `organizationName` | `string` | OrganizationName is the Coder organization. Defaults to "default". |
1919
| `bootstrap` | `CoderProvisionerBootstrapSpec` | Bootstrap configures credentials for provisioner key management. |
20-
| &nbsp;&nbsp;`credentialsSecretRef` | `SecretKeySelector` | CredentialsSecretRef points to a Secret containing a Coder session token with permission to manage provisioner keys. |
21-
| &nbsp;&nbsp;&nbsp;&nbsp;`name` | `string` | Name is the Kubernetes Secret name. |
22-
| &nbsp;&nbsp;&nbsp;&nbsp;`key` | `string` | Key is the key inside the Secret data map. |
20+
| └─ `credentialsSecretRef` | `SecretKeySelector` | CredentialsSecretRef points to a Secret containing a Coder session token with permission to manage provisioner keys. |
21+
| &nbsp;&nbsp;&nbsp;├─ `name` | `string` | Name is the Kubernetes Secret name. |
22+
| &nbsp;&nbsp;&nbsp;└─ `key` | `string` | Key is the key inside the Secret data map. |
2323
| `key` | `CoderProvisionerKeySpec` | Key configures provisioner key naming and secret storage. |
24-
| &nbsp;&nbsp;`name` | `string` | Name is the provisioner key name in coderd. Defaults to the CR name. |
25-
| &nbsp;&nbsp;`secretName` | `string` | SecretName is the Kubernetes Secret to store the key. Defaults to "\{crName\}-provisioner-key". |
26-
| &nbsp;&nbsp;`secretKey` | `string` | SecretKey is the data key in the Secret. Defaults to "key". |
24+
| ├─ `name` | `string` | Name is the provisioner key name in coderd. Defaults to the CR name. |
25+
| ├─ `secretName` | `string` | SecretName is the Kubernetes Secret to store the key. Defaults to "\{crName\}-provisioner-key". |
26+
| └─ `secretKey` | `string` | SecretKey is the data key in the Secret. Defaults to "key". |
2727
| `replicas` | `int32` | Replicas is the desired number of provisioner pods. |
2828
| `tags` | `map[string]string` | Tags are attached to the provisioner key for job routing. |
2929
| `image` | `string` | Image is the container image. Defaults to the control plane image. |
3030
| `extraArgs` | `[]string` | ExtraArgs are appended after "provisionerd start". |
3131
| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the provisioner container. |
3232
| `resources` | `corev1.ResourceRequirements` | Resources for the provisioner container. |
3333
| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. |
34-
| &nbsp;&nbsp;`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) |
34+
| └─ `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) |
3535
| `terminationGracePeriodSeconds` | `int64` | TerminationGracePeriodSeconds for the provisioner pods. |
3636

3737
## Status
@@ -50,8 +50,8 @@
5050
| `controlPlaneRefName` | `string` | ControlPlaneRefName is the control plane ref name last applied to the provisioner key. |
5151
| `controlPlaneURL` | `string` | ControlPlaneURL is the control plane URL last applied to the provisioner key. |
5252
| `secretRef` | `SecretKeySelector` | SecretRef references the provisioner key secret data currently in use. |
53-
| &nbsp;&nbsp;`name` | `string` | Name is the Kubernetes Secret name. |
54-
| &nbsp;&nbsp;`key` | `string` | Key is the key inside the Secret data map. |
53+
| ├─ `name` | `string` | Name is the Kubernetes Secret name. |
54+
| └─ `key` | `string` | Key is the key inside the Secret data map. |
5555

5656
## Source
5757

‎docs/reference/api/workspaceproxy.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,27 +16,27 @@
1616
| `image` | `string` | Image is the container image used for the workspace proxy pod. |
1717
| `replicas` | `int32` | Replicas is the desired number of proxy pods. |
1818
| `service` | `ServiceSpec` | Service controls the service created in front of the workspace proxy. |
19-
| &nbsp;&nbsp;`type` | `corev1.ServiceType` | Type controls the Kubernetes service type. |
20-
| &nbsp;&nbsp;`port` | `int32` | Port controls the exposed service port. |
21-
| &nbsp;&nbsp;`annotations` | `map[string]string` | Annotations are applied to the reconciled service object. |
19+
| ├─ `type` | `corev1.ServiceType` | Type controls the Kubernetes service type. |
20+
| ├─ `port` | `int32` | Port controls the exposed service port. |
21+
| └─ `annotations` | `map[string]string` | Annotations are applied to the reconciled service object. |
2222
| `primaryAccessURL` | `string` | PrimaryAccessURL is the coderd URL the proxy should connect to. |
2323
| `proxySessionTokenSecretRef` | `SecretKeySelector` | ProxySessionTokenSecretRef points to a Secret key containing the proxy token. |
24-
| &nbsp;&nbsp;`name` | `string` | Name is the Kubernetes Secret name. |
25-
| &nbsp;&nbsp;`key` | `string` | Key is the key inside the Secret data map. |
24+
| ├─ `name` | `string` | Name is the Kubernetes Secret name. |
25+
| └─ `key` | `string` | Key is the key inside the Secret data map. |
2626
| `bootstrap` | `ProxyBootstrapSpec` | Bootstrap optionally registers the proxy and mints a proxy token. |
27-
| &nbsp;&nbsp;`coderURL` | `string` | CoderURL is the URL for the primary Coder control plane API. |
28-
| &nbsp;&nbsp;`credentialsSecretRef` | `SecretKeySelector` | CredentialsSecretRef points to a Secret containing a Coder session token. |
29-
| &nbsp;&nbsp;&nbsp;&nbsp;`name` | `string` | Name is the Kubernetes Secret name. |
30-
| &nbsp;&nbsp;&nbsp;&nbsp;`key` | `string` | Key is the key inside the Secret data map. |
31-
| &nbsp;&nbsp;`proxyName` | `string` | ProxyName is the name used when registering the proxy in Coder. |
32-
| &nbsp;&nbsp;`displayName` | `string` | DisplayName is the human-readable name for the proxy region. |
33-
| &nbsp;&nbsp;`icon` | `string` | Icon is the optional icon URL or emoji path for the proxy region. |
34-
| &nbsp;&nbsp;`generatedTokenSecretName` | `string` | GeneratedTokenSecretName stores the generated proxy token. |
27+
| ├─ `coderURL` | `string` | CoderURL is the URL for the primary Coder control plane API. |
28+
| ├─ `credentialsSecretRef` | `SecretKeySelector` | CredentialsSecretRef points to a Secret containing a Coder session token. |
29+
| │&nbsp;&nbsp;├─ `name` | `string` | Name is the Kubernetes Secret name. |
30+
| │&nbsp;&nbsp;└─ `key` | `string` | Key is the key inside the Secret data map. |
31+
| ├─ `proxyName` | `string` | ProxyName is the name used when registering the proxy in Coder. |
32+
| ├─ `displayName` | `string` | DisplayName is the human-readable name for the proxy region. |
33+
| ├─ `icon` | `string` | Icon is the optional icon URL or emoji path for the proxy region. |
34+
| └─ `generatedTokenSecretName` | `string` | GeneratedTokenSecretName stores the generated proxy token. |
3535
| `derpOnly` | `bool` | DerpOnly configures the workspace proxy to only serve DERP traffic. |
3636
| `extraArgs` | `[]string` | ExtraArgs are appended to the default workspace proxy arguments. |
3737
| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the workspace proxy container. |
3838
| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. |
39-
| &nbsp;&nbsp;`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) |
39+
| └─ `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) |
4040

4141
## Status
4242

@@ -46,8 +46,8 @@
4646
| `readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. |
4747
| `registered` | `bool` | Registered reports whether bootstrap registration completed successfully. |
4848
| `proxyTokenSecretRef` | `SecretKeySelector` | ProxyTokenSecretRef is the Secret used for the proxy session token. |
49-
| &nbsp;&nbsp;`name` | `string` | Name is the Kubernetes Secret name. |
50-
| &nbsp;&nbsp;`key` | `string` | Key is the key inside the Secret data map. |
49+
| ├─ `name` | `string` | Name is the Kubernetes Secret name. |
50+
| └─ `key` | `string` | Key is the key inside the Secret data map. |
5151
| `phase` | `string` | Phase is a high-level readiness indicator. |
5252
| `conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. |
5353

‎hack/crd-ref-docs/templates/markdown/gv_list.tpl‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@
1717
{{- $fields := .fields -}}
1818
{{- $depth := int .depth -}}
1919
{{- $maxDepth := int .maxDepth -}}
20-
{{- $indent := repeat $depth "&nbsp;&nbsp;" -}}
21-
{{- range $field := $fields }}
20+
{{- $treePrefix := .treePrefix -}}
21+
{{- $fieldCount := len $fields -}}
22+
{{- range $index, $field := $fields }}
2223
{{- if not $field.Type }}{{ fail (printf "field %q is missing type information" $field.Name) }}{{- end }}
2324
{{- $memberType := $field.Type -}}
2425
{{- $members := $memberType.Members -}}
@@ -27,11 +28,30 @@
2728
{{- $isProjectLocal := contains "github.com/coder/coder-k8s/api/" $memberTypeString -}}
2829
{{- $isLocalObjectRef := contains "k8s.io/api/core/v1.LocalObjectReference" $memberTypeString -}}
2930
{{- $shouldExpand := and $hasMembers (lt $depth $maxDepth) (or $isProjectLocal $isLocalObjectRef) -}}
31+
{{- $isLast := eq (add $index 1) $fieldCount -}}
32+
{{- $branch := "" -}}
33+
{{- if gt $depth 0 -}}
34+
{{- if $isLast -}}
35+
{{- $branch = "└─ " -}}
36+
{{- else -}}
37+
{{- $branch = "├─ " -}}
38+
{{- end -}}
39+
{{- end -}}
3040
{{- $fieldDoc := markdownRenderFieldDoc $field.Doc -}}
3141
{{- $fieldDoc = $fieldDoc | replace "<br />" " " -}}
3242
{{- $fieldDoc = regexReplaceAll "(https?://[^[:space:]<]+)" $fieldDoc "[$1]($1)" -}}
33-
| {{ $indent }}`{{ $field.Name }}` | `{{ template "typeName" $memberType }}` | {{ $fieldDoc }} |
34-
{{ if $shouldExpand }}{{ template "renderFields" (dict "fields" $members "depth" (add $depth 1) "maxDepth" $maxDepth) }}{{ end }}
43+
| {{ $treePrefix }}{{ $branch }}`{{ $field.Name }}` | `{{ template "typeName" $memberType }}` | {{ $fieldDoc }} |
44+
{{ $childPrefix := $treePrefix -}}
45+
{{- if gt $depth 0 -}}
46+
{{- if $isLast -}}
47+
{{- $childPrefix = printf "%s&nbsp;&nbsp;&nbsp;" $treePrefix -}}
48+
{{- else -}}
49+
{{- $childPrefix = printf "%s│&nbsp;&nbsp;" $treePrefix -}}
50+
{{- end -}}
51+
{{- else -}}
52+
{{- $childPrefix = "" -}}
53+
{{- end -}}
54+
{{ if $shouldExpand }}{{ template "renderFields" (dict "fields" $members "depth" (add $depth 1) "maxDepth" $maxDepth "treePrefix" $childPrefix) }}{{ end }}
3555
{{- end -}}
3656
{{- end -}}
3757

@@ -103,12 +123,12 @@
103123

104124
| Field | Type | Description |
105125
| --- | --- | --- |
106-
{{ template "renderFields" (dict "fields" $specMembers "depth" 0 "maxDepth" $maxFieldDepth) }}
126+
{{ template "renderFields" (dict "fields" $specMembers "depth" 0 "maxDepth" $maxFieldDepth "treePrefix" "") }}
107127
## Status
108128

109129
| Field | Type | Description |
110130
| --- | --- | --- |
111-
{{ template "renderFields" (dict "fields" $statusMembers "depth" 0 "maxDepth" $maxFieldDepth) }}
131+
{{ template "renderFields" (dict "fields" $statusMembers "depth" 0 "maxDepth" $maxFieldDepth "treePrefix" "") }}
112132
## Source
113133

114134
- Go type: `{{ $goType }}`

0 commit comments

Comments
 (0)