CRD reference docs are not multi version aware #446
Description
Problem statement
This project uses https://github.com/elastic/crd-ref-docs/ to produce the CRD reference documentation that's stored in https://github.com/Kong/kubernetes-configuration/tree/af85dfab1f9fe29e71fdbcce55ffe8394833f477/docs.
crd-ref-docs does not work well with CRDs that define more than 1 API version. The problem lies in produced markdown link anchors which are not version aware, e.g. https://github.com/Kong/kubernetes-configuration/pull/441/files/b49858ce6fda1d3267517ec7f9d150cdf4a3f6f5#diff-1dcae06dc19c48c1a286203ce335f2967fd00f47275a34a530efe517733306a7R1303.
This issue tracks the fix for this problem.
Additional context
There seems to be an issue created upstream for this problem: elastic/crd-ref-docs#60 and a PR that fixes it elastic/crd-ref-docs#118 but after building it locally and producing documentation it seems that the issue is partially solved as it produces version aware anchors but the section titles are not updated.
diff --git a/docs/all-api-reference.md b/docs/all-api-reference.md
index bf87b56..08a9fc6 100644
--- a/docs/all-api-reference.md
+++ b/docs/all-api-reference.md
@@ -1,24 +1,24 @@
<!-- This document is generated by kong/kubernetes-configuration's 'generate.docs' make target, DO NOT EDIT -->
## Packages
-- [configuration.konghq.com/v1](#configurationkonghqcomv1)
-- [configuration.konghq.com/v1alpha1](#configurationkonghqcomv1alpha1)
-- [configuration.konghq.com/v1beta1](#configurationkonghqcomv1beta1)
-- [gateway-operator.konghq.com/v1alpha1](#gateway-operatorkonghqcomv1alpha1)
-- [gateway-operator.konghq.com/v1beta1](#gateway-operatorkonghqcomv1beta1)
-- [gateway-operator.konghq.com/v2alpha1](#gateway-operatorkonghqcomv2alpha1)
-- [incubator.ingress-controller.konghq.com/v1alpha1](#incubatoringress-controllerkonghqcomv1alpha1)
-- [konnect.konghq.com/v1alpha1](#konnectkonghqcomv1alpha1)
+- [configuration.konghq.com/v1](#configuration-konghq-com-v1)
+- [configuration.konghq.com/v1alpha1](#configuration-konghq-com-v1alpha1)
+- [configuration.konghq.com/v1beta1](#configuration-konghq-com-v1beta1)
+- [gateway-operator.konghq.com/v1alpha1](#gateway-operator-konghq-com-v1alpha1)
+- [gateway-operator.konghq.com/v1beta1](#gateway-operator-konghq-com-v1beta1)
+- [gateway-operator.konghq.com/v2alpha1](#gateway-operator-konghq-com-v2alpha1)
+- [incubator.ingress-controller.konghq.com/v1alpha1](#incubator-ingress-controller-konghq-com-v1alpha1)
+- [konnect.konghq.com/v1alpha1](#konnect-konghq-com-v1alpha1)
## configuration.konghq.com/v1
Package v1 contains API Schema definitions for the konghq.com v1 API group.
-- [KongClusterPlugin](#kongclusterplugin)
-- [KongConsumer](#kongconsumer)
-- [KongIngress](#kongingress)
-- [KongPlugin](#kongplugin)
+- [KongClusterPlugin](#github-com-kong-kubernetes-configuration-api-configuration-v1-kongclusterplugin)
+- [KongConsumer](#github-com-kong-kubernetes-configuration-api-configuration-v1-kongconsumer)
+- [KongIngress](#github-com-kong-kubernetes-configuration-api-configuration-v1-kongingress)
+- [KongPlugin](#github-com-kong-kubernetes-configuration-api-configuration-v1-kongplugin)
### KongClusterPlugin
@@ -34,12 +34,12 @@ KongClusterPlugin is the Schema for the kongclusterplugins API.
| `consumerRef` _string_ | ConsumerRef is a reference to a particular consumer. |
| `disabled` _boolean_ | Disabled set if the plugin is disabled or not. |
| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.33/#json-v1-apiextensions-k8s-io)_ | Config contains the plugin configuration. It's a list of keys and values required to configure the plugin. Please read the documentation of the plugin being configured to set values in here. For any plugin in Kong, anything that goes in the `config` JSON key in the Admin API request, goes into this property. Only one of `config` or `configFrom` may be used in a KongClusterPlugin, not both at once. |
-| `configFrom` _[NamespacedConfigSource](#namespacedconfigsource)_ | ConfigFrom references a secret containing the plugin configuration. This should be used when the plugin configuration contains sensitive information, such as AWS credentials in the Lambda plugin or the client secret in the OIDC plugin. Only one of `config` or `configFrom` may be used in a KongClusterPlugin, not both at once. |
-| `configPatches` _[NamespacedConfigPatch](#namespacedconfigpatch) array_ | ConfigPatches represents JSON patches to the configuration of the plugin. Each item means a JSON patch to add something in the configuration, where path is
specified in `path` and value is in `valueFrom` referencing a key in a secret. When Config is specified, patches will be applied to the configuration in Config. Otherwise, patches will be applied to an empty object. |
+| `configFrom` _[NamespacedConfigSource](#github-com-kong-kubernetes-configuration-api-configuration-v1-namespacedconfigsource)_ | ConfigFrom references a secret containing the plugin configuration. This should be used when the plu
gin configuration contains sensitive information, such as AWS credentials in the Lambda plugin or the client secret in the OIDC plugin. Only one of `config` or `configFrom` may be used in a KongClusterPlugin, not both at once. |
+| `configPatches` _[NamespacedConfigPatch](#github-com-kong-kubernetes-configuration-api-configuration-v1-namespacedconfigpatch) array_ | ConfigPatches represents JSON patches to the configuration of the plugin. Each item means a J
SON patch to add something in the configuration, where path is specified in `path` and value is in `valueFrom` referencing a key in a secret. When Config is specified, patches will be applied to the configuration in Config. Otherwis
e, patches will be applied to an empty object. |
| `plugin` _string_ | PluginName is the name of the plugin to which to apply the config. |
| `run_on` _string_ | RunOn configures the plugin to run on the first or the second or both nodes in case of a service mesh deployment. |
-| `protocols` _[KongProtocol](#kongprotocol) array_ | Protocols configures plugin to run on requests received on specific protocols. |
-| `ordering` _[PluginOrdering](#pluginordering)_ | Ordering overrides the normal plugin execution order. It's only available on Kong Enterprise. `<phase>` is a request processing phase (for example, `access` or `body_filter`) and `
<plugin>` is the name of the plugin that will run before or after the KongPlugin. For example, a KongPlugin with `plugin: rate-limiting` and `before.access: ["key-auth"]` will create a rate limiting plugin that limits requests _before_ they are authenticated. |
+| `protocols` _[KongProtocol](#github-com-kong-kubernetes-configuration-api-configuration-v1-kongprotocol) array_ | Protocols configures plugin to run on requests received on specific protocols. |
+| `ordering` _[PluginOrdering](#github-com-kong-go-kong-kong-pluginordering)_ | Ordering overrides the normal plugin execution order. It's only available on Kong Enterprise. `<phase>` is a request processing phase (for example, `access` or `body_filter`) and `<plugin>` is the name of the plugin that will run before or after the KongPlugin. For example, a KongPlugin with `plugin: rate-limiting` and `before.access: ["key-auth"]` will create a rate limiting plugin that limits requests _before_ they are authenticated. |
| `instance_name` _string_ | InstanceName is an optional custom name to identify an instance of the plugin. This is useful when running the same plugin in multiple contexts, for example, on multiple services. |Acceptance criteria
- The CRD reference documentation produced by tooling in this repo produces markdown with version aware link anchors.