🤖 fix: make generated CRD API docs YAML-oriented (#59)

Summary
Improves generated CRD API reference docs so they read more like YAML
users actually write, with cleaner field/type names and selective
nested-object expansion for actionable object fields.

Background
The generated docs were hard to use because table keys repeated
`spec.`/`status.`, type names included noisy fully-qualified package
paths, and object-like fields (for example `LocalObjectReference`) did
not show nested members users need in YAML.

Implementation
- Updated `hack/crd-ref-docs/templates/markdown/gv_list.tpl`:
  - removed redundant `spec.` / `status.` prefixes from table rows.
- shortened common type package paths (`metav1`, `corev1`, and local API
types).
- added a recursive `renderFields` template for nested field expansion.
- constrained expansion to project-local API types and
`corev1.LocalObjectReference` with depth limit 3 to avoid doc bloat.
- Regenerated API reference outputs under `docs/reference/api/*.md`.

Validation
- `make verify-vendor`
- `make test`
- `make build`
- `make lint`
- `make docs-reference`
- `make docs-check`

Risks
Low to moderate. This changes only documentation generation templates
and generated markdown output, not runtime behavior. Main risk is doc
rendering regressions; mitigated by successful `make docs-check` (strict
mkdocs build) and regeneration checks.

---

<details>
<summary>📋 Implementation Plan</summary>

# Plan: Make CRD API reference docs read like YAML (nested + less
verbose)

## Context / Why
The current generated API reference docs (e.g.
`docs/reference/api/coderprovisioner.md`) are hard for users to act on:

- The **Field** column repeats `spec.` / `status.` even though the table
is already under `## Spec` / `## Status`.
- The **Type** column shows **fully-qualified Go package paths**, which
is noisy.
- Most importantly, **nested struct types are opaque** (e.g.
`controlPlaneRef` is a `corev1.LocalObjectReference`, but the docs don’t
show that the YAML must contain `name:`). Users don’t know what to
write.

Goal: adjust the `crd-ref-docs` markdown template so the output is:

- easier to scan,
- closer to the YAML structure people actually write,
- and provides actionable detail for “object” fields (at least for the
important/commonly-confusing ones like `LocalObjectReference`).

## Evidence (what we verified)
- API reference docs are generated by `crd-ref-docs` via
`hack/update-reference-docs.sh` / `make docs-reference`.
(`hack/update-reference-docs.sh`, `hack/crd-ref-docs/config.yaml`)
- Output is a simple flat table produced by
`hack/crd-ref-docs/templates/markdown/gv_list.tpl`.
- The example in the screenshot matches
`docs/reference/api/coderprovisioner.md`.
- `crd-ref-docs` represents nested types via `types.Type` with a
`Members()` method that returns struct fields even through
aliases/slices/pointers.
(`vendor/github.com/elastic/crd-ref-docs/types/types.go`)

## Implementation details

### 1) Remove redundant `spec.` / `status.` prefixes
**File:** `hack/crd-ref-docs/templates/markdown/gv_list.tpl`

- Change the rows under `## Spec` from:

```go-template
| `spec.{{ $member.Name }}` | ... |
```

to:

```go-template
| `{{ $member.Name }}` | ... |
```

- Change the rows under `## Status` from:

```go-template
| `status.{{ $member.Name }}` | ... |
```

to:

```go-template
| `{{ $member.Name }}` | ... |
```

**Result:** tables read like the YAML keys a user will set under `spec:`
/ `status:`.

---

### 2) Bonus: Clean up verbose Go type paths in the `Type` column
**File:** `hack/crd-ref-docs/templates/markdown/gv_list.tpl` (the
`typeName` helper)

Update `typeName` to replace noisy package paths with common aliases /
short names.

Proposed replacements (minimal, focused on what we see in our CRDs):

- `k8s.io/apimachinery/pkg/apis/meta/v1.` → `metav1.` (already present)
- `k8s.io/api/core/v1.` → `corev1.`
- `github.com/coder/coder-k8s/api/v1alpha1.` → `` (strip to just the
type name)

Shape:

```go-template
{{- $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 -}}
```

**Result:** types become readable (`corev1.LocalObjectReference`,
`CoderProvisionerKeySpec`, etc.) without losing meaning.

---

### 3) Show nested fields for selected “object” types (so users know
what to write)
**File:** `hack/crd-ref-docs/templates/markdown/gv_list.tpl`

Replace the flat `range $specMembers` / `range $statusMembers` rendering
with a small recursive renderer that can optionally expand struct
members.

#### 3.1) Expansion policy (avoid doc bloat)
We should not blindly expand every imported Kubernetes type (e.g.
`corev1.EnvVar` can recursively explode). Instead, expand only when:

- The field’s type has members (`len $t.Members > 0`), and
- The type is either:
- **Project-local** (`$t.Package` starts with
`github.com/coder/coder-k8s/api/`), or
- A small, commonly-confusing external wrapper like
**`k8s.io/api/core/v1.LocalObjectReference`**.

Add a simple depth limit (e.g. `maxDepth := 3`) to prevent runaway
recursion.

#### 3.2) Table rendering shape
Add a new template block (name is flexible) that prints rows for a list
of fields and can recurse:

```go-template
{{- define "renderFields" -}}
{{- $fields := index . 0 -}}
{{- $depth := index . 1 -}}
{{- $maxDepth := index . 2 -}}
{{- $indent := repeat $depth "&nbsp;&nbsp;" -}}

{{- range $f := $fields }}
{{- if not $f.Type -}}
{{ fail (printf "field %q is missing type information" $f.Name) }}
{{- end -}}

{{- $t := $f.Type -}}
{{- $hasMembers := gt (len $t.Members) 0 -}}
{{- $isProjectLocal := hasPrefix $t.Package "github.com/coder/coder-k8s/api/" -}}
{{- $isLocalObjectRef := and (eq $t.Package "k8s.io/api/core/v1") (eq $t.Name "LocalObjectReference") -}}
{{- $shouldExpand := and $hasMembers (lt $depth $maxDepth) (or $isProjectLocal $isLocalObjectRef) -}}

| {{ $indent }}`{{ $f.Name }}` | `{{ template "typeName" $t }}` | {{ markdownRenderFieldDoc $f.Doc }} |
{{- if $shouldExpand }}
{{- template "renderFields" (list $t.Members (add $depth 1) $maxDepth) -}}
{{- end }}
{{- end }}
{{- end -}}
```

Then render spec/status like:

```go-template
## Spec

| Field | Type | Description |
| --- | --- | --- |
{{- template "renderFields" (list $specMembers 0 3) }}

## Status

| Field | Type | Description |
| --- | --- | --- |
{{- template "renderFields" (list $statusMembers 0 3) }}
```

**Result:** users will see `controlPlaneRef` → `name` (and other small
structs) directly in the table, without needing to understand Go types.

<details>
<summary>Why this policy (and not “expand everything”)?</summary>

Expanding every imported Kubernetes type tends to create huge,
hard-to-navigate pages and slows review. The hybrid approach targets the
worst UX offenders (object refs and project-local structs) while keeping
common K8s “implementation detail” structs as a single row.

Follow-up options if we want more detail later:
- allowlist additional external types (e.g. `metav1.LabelSelector`),
- add per-type `<details>` blocks instead of in-table recursion,
- or render linked “Type sections” further down the page.
</details>

---

### 4) Regenerate reference docs and confirm output
After template changes, regenerate docs so the repo reflects the new
format.

- Run: `make docs-reference` (or `bash hack/update-reference-docs.sh`)
- Confirm:
- `docs/reference/api/coderprovisioner.md` no longer has `spec.` /
`status.` prefixes.
  - `controlPlaneRef` expands to show `name`.
  - Type strings are shortened as expected.
  - `mkdocs.yml` nav updates (if the script touches it).

## Validation
- `make docs-reference` (ensures generator + templates work and output
is updated)
- `make docs-check` (ensures the docs site still builds)
- (Optional but recommended) `make test` (sanity check; should be
unchanged but cheap to verify)

</details>

---

_Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking:
`xhigh` • Cost: $0.53_

<!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh
costs=0.53 -->

Author: ThomasK33

.cspell.json

@@ -31,6 +31,7 @@
     "javascripts",
     "kubeconfig",
     "kubebuilder",
+    "corev",
     "metav",
     "mkdocs",
     "pymdownx",

docs/reference/api/codercontrolplane.md

@@ -13,25 +13,33 @@
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `spec.image` | `string` | Image is the container image used for the Coder control plane pod. |
-| `spec.replicas` | `int32` | Replicas is the desired number of control plane pods. |
-| `spec.service` | `github.com/coder/coder-k8s/api/v1alpha1.ServiceSpec` | Service controls the service created in front of the control plane. |
-| `spec.extraArgs` | `[]string` | ExtraArgs are appended to the default Coder server arguments. |
-| `spec.extraEnv` | `[]k8s.io/api/core/v1.EnvVar` | ExtraEnv are injected into the Coder control plane container. |
-| `spec.imagePullSecrets` | `[]k8s.io/api/core/v1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. |
-| `spec.operatorAccess` | `github.com/coder/coder-k8s/api/v1alpha1.OperatorAccessSpec` | OperatorAccess configures bootstrap API access to the coderd instance. |
+| `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. |
 
 ## Status
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `status.observedGeneration` | `int64` | ObservedGeneration tracks the spec generation this status reflects. |
-| `status.readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. |
-| `status.url` | `string` | URL is the in-cluster URL for the control plane service. |
-| `status.operatorTokenSecretRef` | `github.com/coder/coder-k8s/api/v1alpha1.SecretKeySelector` | OperatorTokenSecretRef points to the Secret key containing the `coder-k8s-operator` API token. |
-| `status.operatorAccessReady` | `bool` | OperatorAccessReady reports whether operator API access bootstrap succeeded. |
-| `status.phase` | `string` | Phase is a high-level readiness indicator. |
-| `status.conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. |
+| `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. |
 
 ## Source
 

docs/reference/api/coderprovisioner.md

@@ -13,35 +13,45 @@
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `spec.controlPlaneRef` | `k8s.io/api/core/v1.LocalObjectReference` | ControlPlaneRef identifies which CoderControlPlane instance to join. |
-| `spec.organizationName` | `string` | OrganizationName is the Coder organization. Defaults to "default". |
-| `spec.bootstrap` | `github.com/coder/coder-k8s/api/v1alpha1.CoderProvisionerBootstrapSpec` | Bootstrap configures credentials for provisioner key management. |
-| `spec.key` | `github.com/coder/coder-k8s/api/v1alpha1.CoderProvisionerKeySpec` | Key configures provisioner key naming and secret storage. |
-| `spec.replicas` | `int32` | Replicas is the desired number of provisioner pods. |
-| `spec.tags` | `map[string]string` | Tags are attached to the provisioner key for job routing. |
-| `spec.image` | `string` | Image is the container image. Defaults to the control plane image. |
-| `spec.extraArgs` | `[]string` | ExtraArgs are appended after "provisionerd start". |
-| `spec.extraEnv` | `[]k8s.io/api/core/v1.EnvVar` | ExtraEnv are injected into the provisioner container. |
-| `spec.resources` | `k8s.io/api/core/v1.ResourceRequirements` | Resources for the provisioner container. |
-| `spec.imagePullSecrets` | `[]k8s.io/api/core/v1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. |
-| `spec.terminationGracePeriodSeconds` | `int64` | TerminationGracePeriodSeconds for the provisioner pods. |
+| `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. |
 
 ## Status
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `status.observedGeneration` | `int64` | ObservedGeneration tracks the spec generation this status reflects. |
-| `status.readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. |
-| `status.phase` | `string` | Phase is a high-level readiness indicator. |
-| `status.conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. |
-| `status.organizationID` | `string` | OrganizationID is the organization ID last applied to the provisioner key. |
-| `status.organizationName` | `string` | OrganizationName is the organization name last applied to the provisioner key. |
-| `status.provisionerKeyID` | `string` | ProvisionerKeyID is the provisioner key ID last applied in coderd. |
-| `status.provisionerKeyName` | `string` | ProvisionerKeyName is the provisioner key name last applied in coderd. |
-| `status.tagsHash` | `string` | TagsHash is a deterministic hash of spec.tags last applied to the provisioner key. |
-| `status.controlPlaneRefName` | `string` | ControlPlaneRefName is the control plane ref name last applied to the provisioner key. |
-| `status.controlPlaneURL` | `string` | ControlPlaneURL is the control plane URL last applied to the provisioner key. |
-| `status.secretRef` | `github.com/coder/coder-k8s/api/v1alpha1.SecretKeySelector` | SecretRef references the provisioner key secret data currently in use. |
+| `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. |
 
 ## Source
 

docs/reference/api/codertemplate.md

@@ -13,23 +13,23 @@
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `spec.organization` | `string` | Organization is the Coder organization name (must match the organization prefix in metadata.name). |
-| `spec.versionID` | `string` | VersionID is the Coder template version UUID used on creation (required for CREATE). |
-| `spec.displayName` | `string` |  |
-| `spec.description` | `string` |  |
-| `spec.icon` | `string` |  |
-| `spec.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` | `bool` | Running is a legacy flag retained temporarily for in-repo callers that still read template run-state directly. |
 
 ## Status
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `status.id` | `string` |  |
-| `status.organizationName` | `string` |  |
-| `status.activeVersionID` | `string` |  |
-| `status.deprecated` | `bool` |  |
-| `status.updatedAt` | `metav1.Time` |  |
-| `status.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` | `bool` |  |
+| `updatedAt` | `metav1.Time` |  |
+| `autoShutdown` | `metav1.Time` | AutoShutdown is a legacy timestamp retained temporarily for in-repo callers that still surface template shutdown timestamps. |
 
 ## Source
 

docs/reference/api/coderworkspace.md

@@ -13,25 +13,25 @@
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `spec.organization` | `string` | Organization is the Coder organization name. |
-| `spec.templateName` | `string` | TemplateName resolves via TemplateByName(organization, templateName). |
-| `spec.templateVersionID` | `string` | TemplateVersionID optionally pins to a specific template version. |
-| `spec.running` | `bool` | Running drives start/stop via CreateWorkspaceBuild. |
-| `spec.ttlMillis` | `int64` |  |
-| `spec.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` | `bool` | Running drives start/stop via CreateWorkspaceBuild. |
+| `ttlMillis` | `int64` |  |
+| `autostartSchedule` | `string` |  |
 
 ## Status
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `status.id` | `string` |  |
-| `status.ownerName` | `string` |  |
-| `status.organizationName` | `string` |  |
-| `status.templateName` | `string` |  |
-| `status.latestBuildID` | `string` |  |
-| `status.latestBuildStatus` | `string` |  |
-| `status.autoShutdown` | `metav1.Time` |  |
-| `status.lastUsedAt` | `metav1.Time` |  |
+| `id` | `string` |  |
+| `ownerName` | `string` |  |
+| `organizationName` | `string` |  |
+| `templateName` | `string` |  |
+| `latestBuildID` | `string` |  |
+| `latestBuildStatus` | `string` |  |
+| `autoShutdown` | `metav1.Time` |  |
+| `lastUsedAt` | `metav1.Time` |  |
 
 ## Source