docs: make API reference cross-links version-aware

[harshasiddartha]

Why are these changes needed?

crd-ref-docs derives Markdown anchors from the type name alone, so the eleven types that exist in both ray.io/v1 and ray.io/v1alpha1 (RayClusterSpec, WorkerGroupSpec, RayJob, ...) emit the same anchor twice. Markdown renderers de-duplicate the heading ids (rayclusterspec, rayclusterspec_1) but not the links, so all 23 cross-links in the ray.io/v1alpha1 section of docs/reference/api.md resolved to the ray.io/v1 definition. The failure is silent — no broken link, no warning at generation time — and the definitions differ substantially (RayClusterSpec has 14 fields in v1 and 7 in v1alpha1), so a reader following a v1alpha1 link lands on a table advertising fields that do not exist in v1alpha1.

This is issue direction (1): version-qualified slugs, fixed in the generation step rather than by post-processing the output.

make api-docs now renders through a local copy of the upstream crd-ref-docs Markdown templates (ray-operator/hack/api-docs-templates/). The only change from upstream is that each type heading carries an explicit, version-qualified anchor and every cross-reference resolves against it:

{{- define "typeAnchor" -}}
{{- markdownSafeID (printf "%s-%s" .Name (last (splitList "/" .Package))) -}}
{{- end -}}

Heading text is byte-for-byte unchanged, so the auto-generated ids the published site already exposes (#rayclusterspec, #rayclusterspec_1) still exist and existing external deep links keep working.

Before / after

Heading (RayClusterSpec, ray.io/v1alpha1 section):

-#### RayClusterSpec
+#### <a id="rayclusterspec-v1alpha1" name="rayclusterspec-v1alpha1"></a>RayClusterSpec

Cross-link from AutoscalerOptions in the ray.io/v1alpha1 section:

 _Appears in:_
-- [RayClusterSpec](#rayclusterspec)
+- [RayClusterSpec](#rayclusterspec-v1alpha1)

Field reference in the v1alpha1 RayClusterSpec table:

-| `workerGroupSpecs` _[WorkerGroupSpec](#workergroupspec) array_ | ...
+| `workerGroupSpecs` _[WorkerGroupSpec](#workergroupspec-v1alpha1) array_ | ...

All 23 previously-wrong links in the v1alpha1 section, after regeneration:

2 [AutoscalerOptions](#autoscaleroptions-v1alpha1)
1 [HeadGroupSpec](#headgroupspec-v1alpha1)
6 [RayClusterSpec](#rayclusterspec-v1alpha1)
2 [RayCluster](#raycluster-v1alpha1)
2 [RayJobSpec](#rayjobspec-v1alpha1)
2 [RayJob](#rayjob-v1alpha1)
2 [RayServiceSpec](#rayservicespec-v1alpha1)
2 [RayService](#rayservice-v1alpha1)
1 [ScaleStrategy](#scalestrategy-v1alpha1)
1 [UpscalingMode](#upscalingmode-v1alpha1)
2 [WorkerGroupSpec](#workergroupspec-v1alpha1)

Related issue number

Closes #5091

Labels

• If this PR has user-facing changes that require documentation updates at release time, I have added the doc-updates-required label.
• If this PR contains breaking changes, I have added the breaking-change label.

Checks

• I've made sure the tests are passing.
• Testing Strategy
  • Manual tests

Manual test instructions

cd ray-operator && make api-docs

# every local link target now has a matching explicit anchor;
# the only unanchored targets are the two group-version headings,
# whose auto ids (rayiov1 / rayiov1alpha1) are already unique.
cd ..
grep -oE '\]\(#[a-z0-9_-]*\)' docs/reference/api.md | sed 's/](#//;s/)//' | sort -u > /tmp/targets
grep -oE '<a id="[a-z0-9_-]*"' docs/reference/api.md | sed 's/<a id="//;s/"//' | sort -u > /tmp/anchors
comm -23 /tmp/targets /tmp/anchors   # -> rayiov1, rayiov1alpha1
comm -13 /tmp/targets /tmp/anchors   # -> empty (no orphan anchors)
grep -oE '<a id="[a-z0-9_-]*"' docs/reference/api.md | sort | uniq -d   # -> empty (no duplicates)

# heading text is unchanged, so pre-existing heading ids are preserved
diff <(git show upstream/master:docs/reference/api.md | grep -E '^#### ') \
     <(grep -E '^#### ' docs/reference/api.md | sed -E 's/<a id="[^"]*" name="[^"]*"><\/a>//')

Also verified:

• ./hack/verify-api-docs.sh -> ./hack/../../docs/reference up to date. (regeneration is idempotent, so the consistency check passes)
• go build ./... in ray-operator/ -> clean
• markdownlint-cli@0.44.0 --disable=MD033 on docs/reference/api.md: no new violations; MD024/no-duplicate-heading drops from 12 to 1

MD033 (inline HTML) is already disabled in .pre-commit-config.yaml, so the <a> anchors don't trip the linter. The name attribute is emitted alongside id so the anchors also resolve when the file is viewed on GitHub.

ray-operator/DEVELOPMENT.md notes that the templates are a fork of the upstream ones and should be re-synced when the crd-ref-docs version is bumped.