docs: add package version to resource id

[AndrewChubatiuk]

Added a version prefix to the resource link to prevent collisions.
fixes #2485

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/templates/api/type.tpl">

<violation number="1" location="docs/templates/api/type.tpl:67">
P2: The version-prefix approach meant to prevent anchor collisions is applied inconsistently and uses a non-unique key. Two concerns for the generated API docs:

1. Member sub-anchors are left unversioned. In the member row the `id` is still built as `lower(sprintf "%s-%s" $type.Name $member.Name)` with no version prefix, while the enclosing type heading is now `#<version>-<typeName>`. If the same type name exists in more than one version (the scenario this PR targets), the member anchors derived from `typeName-memberName` will still collide across those versions on the same page, so the collision this change claims to fix is only partially addressed.

2. The version key is only the last path segment of `Package` (`splitList "/" | last`), which is the API version and not a unique package identifier. For example both `api/operator/v1beta1` and `api/victoriametrics/v1beta1` reduce to the same `v1beta1` key, so same-named types in different API groups sharing a version would still produce duplicate `#v1beta1-<name>` anchors. Consider deriving the anchor from the full package path (or at least group+version) so the generated ids are unique, and apply the same versioning to member anchors and the "Resource Types" / cross-reference links so every anchor stays consistent.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The version-prefix approach meant to prevent anchor collisions is applied inconsistently and uses a non-unique key. Two concerns for the generated API docs:

1. Member sub-anchors are left unversioned. In the member row the id is still built as lower(sprintf "%s-%s" $type.Name $member.Name) with no version prefix, while the enclosing type heading is now #<version>-<typeName>. If the same type name exists in more than one version (the scenario this PR targets), the member anchors derived from typeName-memberName will still collide across those versions on the same page, so the collision this change claims to fix is only partially addressed.

2. The version key is only the last path segment of Package (splitList "/" | last), which is the API version and not a unique package identifier. For example both api/operator/v1beta1 and api/victoriametrics/v1beta1 reduce to the same v1beta1 key, so same-named types in different API groups sharing a version would still produce duplicate #v1beta1-<name> anchors. Consider deriving the anchor from the full package path (or at least group+version) so the generated ids are unique, and apply the same versioning to member anchors and the "Resource Types" / cross-reference links so every anchor stays consistent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/templates/api/type.tpl, line 67:

<comment>The version-prefix approach meant to prevent anchor collisions is applied inconsistently and uses a non-unique key. Two concerns for the generated API docs:

1. Member sub-anchors are left unversioned. In the member row the `id` is still built as `lower(sprintf "%s-%s" $type.Name $member.Name)` with no version prefix, while the enclosing type heading is now `#<version>-<typeName>`. If the same type name exists in more than one version (the scenario this PR targets), the member anchors derived from `typeName-memberName` will still collide across those versions on the same page, so the collision this change claims to fix is only partially addressed.

2. The version key is only the last path segment of `Package` (`splitList "/" | last`), which is the API version and not a unique package identifier. For example both `api/operator/v1beta1` and `api/victoriametrics/v1beta1` reduce to the same `v1beta1` key, so same-named types in different API groups sharing a version would still produce duplicate `#v1beta1-<name>` anchors. Consider deriving the anchor from the full package path (or at least group+version) so the generated ids are unique, and apply the same versioning to member anchors and the "Resource Types" / cross-reference links so every anchor stays consistent.</comment>

<file context>
@@ -33,15 +33,41 @@
+{{- $version := $type.Package | splitList "/" | last }}
 
-#### {{ $type.Name }}
+#### {{ $type.Name }} {#{{ lower (printf "%s-%s" $version $type.Name) }}}
 {{- if $type.IsAlias }}
 
</file context>