Add custom link declaration support for known types (#37)

This adds support for declaring custom links for any known type. ---------- Signed-off-by: hejianpeng <hejianpeng2@huawei.com>
elastic · Apr 24, 2023 · 6be6bcc · 6be6bcc
1 parent 0da28c4
commit 6be6bcc
Show file tree

Hide file tree

Showing 10 changed files with 1,048 additions and 245 deletions.
diff --git a/README.md b/README.md
@@ -68,4 +68,9 @@ processor:
 render:
   # Version of Kubernetes to use when generating links to Kubernetes API documentation.
   kubernetesVersion: 1.22
+  # Generate better link for known types
+  knownTypes:
+    - name: SecretObjectReference
+      package: sigs.k8s.io/gateway-api/apis/v1beta1
+      link: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference
 ```
diff --git a/config.yaml b/config.yaml
@@ -11,3 +11,7 @@ processor:
 
 render:
   kubernetesVersion: 1.22
+  knownTypes:
+    - name: SecretObjectReference
+      package: sigs.k8s.io/gateway-api/apis/v1beta1
+      link: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference
diff --git a/config/config.go b/config/config.go
@@ -37,7 +37,14 @@ type ProcessorConfig struct {
 }
 
 type RenderConfig struct {
-	KubernetesVersion string `json:"kubernetesVersion"`
+	KnownTypes        []*KnownType `json:"knownTypes"`
+	KubernetesVersion string       `json:"kubernetesVersion"`
+}
+
+type KnownType struct {
+	Name    string `json:"name"`
+	Package string `json:"package"`
+	Link    string `json:"link"`
 }
 
 type Flags struct {

diff --git a/renderer/functions.go b/renderer/functions.go
@@ -74,6 +74,10 @@ func (f *Functions) LinkForType(t *types.Type) (link string, local bool) {
 		return f.LinkForKubeType(t), false
 	}
 
+	if kt, ok := f.IsKnownType(t); ok {
+		return f.LinkForKnownType(kt), false
+	}
+
 	if t.IsBasic() || t.Imported {
 		return "", false
 	}
@@ -113,6 +117,20 @@ func (f *Functions) BasicTypeName(name string) string {
 	}
 }
 
+func (f *Functions) IsKnownType(t *types.Type) (*config.KnownType, bool) {
+	for _, kt := range f.conf.Render.KnownTypes {
+		if kt.Package == t.Package && t.Name == kt.Name {
+			return kt, true
+		}
+	}
+
+	return nil, false
+}
+
+func (f *Functions) LinkForKnownType(kt *config.KnownType) string {
+	return kt.Link
+}
+
 type kubernetesHelper struct {
 	kubeVersion     string
 	packagesRegex   *regexp.Regexp

diff --git a/test/api/v1/guestbook_types.go b/test/api/v1/guestbook_types.go
@@ -19,6 +19,7 @@ package v1
 
 import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	gwapiv1b1 "sigs.k8s.io/gateway-api/apis/v1beta1"
 )
 
 // +kubebuilder:object:root=true
@@ -57,6 +58,8 @@ type GuestbookSpec struct {
 	Selector metav1.LabelSelector `json:"selector,omitempty"`
 	// Headers contains a list of header items to include in the page
 	Headers []GuestbookHeader `json:"headers,omitempty"`
+	// CertificateRef is a reference to a secret containing a certificate
+	CertificateRef gwapiv1b1.SecretObjectReference `json:"certificateRef"`
 }
 
 // GuestbookEntry defines an entry in a guest book.

diff --git a/test/config.yaml b/test/config.yaml
@@ -9,3 +9,7 @@ processor:
 
 render:
   kubernetesVersion: 1.22
+  knownTypes:
+    - name: SecretObjectReference
+      package: sigs.k8s.io/gateway-api/apis/v1beta1
+      link: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference
diff --git a/test/expected.asciidoc b/test/expected.asciidoc
@@ -150,6 +150,7 @@ GuestbookSpec defines the desired state of Guestbook.
 | *`entries`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-guestbookentry[$$GuestbookEntry$$] array__ | Entries contain guest book entries for the page
 | *`selector`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#labelselector-v1-meta[$$LabelSelector$$]__ | Selector selects something
 | *`headers`* __xref:{anchor_prefix}-github-com-elastic-crd-ref-docs-api-v1-guestbookheader[$$GuestbookHeader$$] array__ | Headers contains a list of header items to include in the page
+| *`certificateRef`* __link:https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference[$$SecretObjectReference$$]__ | CertificateRef is a reference to a secret containing a certificate
 |===
 
 

diff --git a/test/expected.md b/test/expected.md
@@ -129,6 +129,7 @@ _Appears in:_
 | `entries` _[GuestbookEntry](#guestbookentry) array_ | Entries contain guest book entries for the page |
 | `selector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#labelselector-v1-meta)_ | Selector selects something |
 | `headers` _[GuestbookHeader](#guestbookheader) array_ | Headers contains a list of header items to include in the page |
+| `certificateRef` _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.SecretObjectReference)_ | CertificateRef is a reference to a secret containing a certificate |
 
 
 

diff --git a/test/go.mod b/test/go.mod
@@ -3,10 +3,12 @@ module github.com/elastic/crd-ref-docs
 go 1.13
 
 require (
-	github.com/go-logr/logr v0.1.0
-	github.com/onsi/ginkgo v1.11.0
-	github.com/onsi/gomega v1.8.1
-	k8s.io/apimachinery v0.17.2
-	k8s.io/client-go v0.17.2
-	sigs.k8s.io/controller-runtime v0.5.0
+	github.com/go-logr/logr v1.2.3
+	github.com/onsi/ginkgo v1.16.5
+	github.com/onsi/gomega v1.23.0
+	k8s.io/apimachinery v0.26.0
+	k8s.io/client-go v0.26.0
+	k8s.io/klog v1.0.0 // indirect
+	sigs.k8s.io/controller-runtime v0.12.1
+	sigs.k8s.io/gateway-api v0.6.2
 )