docs: Transition to crd-ref-docs

Update to use crd-ref-docs which is actively maintained and includes
improvements over gen-crd-api-reference-docs.

go.mod

@@ -3,7 +3,7 @@ module sigs.k8s.io/gateway-api
 go 1.22.0
 
 require (
-	github.com/ahmetb/gen-crd-api-reference-docs v0.3.0
+	github.com/elastic/crd-ref-docs v0.0.13-0.20240413123740-ea9fcaa0230f
 	github.com/miekg/dns v1.1.58
 	github.com/stretchr/testify v1.9.0
 	golang.org/x/net v0.24.0
@@ -25,6 +25,9 @@ require (
 )
 
 require (
+	github.com/Masterminds/goutils v1.1.1 // indirect
+	github.com/Masterminds/semver v1.5.0 // indirect
+	github.com/Masterminds/sprig v2.22.0+incompatible // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/emicklei/go-restful/v3 v3.12.0 // indirect
 	github.com/evanphx/json-patch v5.7.0+incompatible // indirect
@@ -35,30 +38,36 @@ require (
 	github.com/go-openapi/jsonreference v0.21.0 // indirect
 	github.com/go-openapi/swag v0.23.0 // indirect
 	github.com/gobuffalo/flect v1.0.2 // indirect
+	github.com/goccy/go-yaml v1.11.3 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/gnostic-models v0.6.8 // indirect
 	github.com/google/go-cmp v0.6.0 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/websocket v1.5.1 // indirect
+	github.com/huandu/xstrings v1.3.3 // indirect
 	github.com/imdario/mergo v0.3.16 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mitchellh/copystructure v1.2.0 // indirect
+	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/moby/spdystream v0.2.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spf13/cobra v1.8.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	go.uber.org/zap v1.27.0 // indirect
+	golang.org/x/crypto v0.22.0 // indirect
 	golang.org/x/exp v0.0.0-20240416160154-fe59bbe5cc7f // indirect
 	golang.org/x/mod v0.17.0 // indirect
 	golang.org/x/oauth2 v0.19.0 // indirect
@@ -67,13 +76,12 @@ require (
 	golang.org/x/text v0.14.0 // indirect
 	golang.org/x/time v0.5.0 // indirect
 	golang.org/x/tools v0.20.0 // indirect
+	golang.org/x/xerrors v0.0.0-20231012003039-104605ab7028 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240227224415-6ceb2ff114de // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/gengo v0.0.0-20230829151522-9cce18d56c01 // indirect
 	k8s.io/gengo/v2 v2.0.0-20240228010128-51d4e06bde70 // indirect
-	k8s.io/klog v0.2.0 // indirect
 	k8s.io/klog/v2 v2.120.1 // indirect
 	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
 )

hack/api-docs/config.yaml

@@ -0,0 +1,15 @@
+processor:
+  ignoreTypes:
+    - "(Elasticsearch|Kibana|ApmServer)List$"
+    - "ParseError$"
+    - "List$"
+    - "ReferencePolicy$"
+  ignoreFields:
+    - "TypeMeta$"
+
+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

hack/api-docs/generate.sh

@@ -29,16 +29,17 @@ readonly HERE=$(cd $(dirname $0) && pwd)
 readonly REPO=$(cd ${HERE}/../.. && pwd)
 
 gendoc::build() {
-    go install github.com/ahmetb/gen-crd-api-reference-docs
+    go install github.com/elastic/crd-ref-docs
 }
 
 # Exec the doc generator.
 gendoc::exec() {
     local readonly confdir="${REPO}/hack/api-docs"
 
-    ${GOBIN}/gen-crd-api-reference-docs \
-        -template-dir ${confdir} \
-        -config ${confdir}/config.json \
+    ${GOBIN}/crd-ref-docs \
+        --templates-dir ${confdir} \
+        --config ${confdir}/config.yaml \
+        --renderer markdown \
         "$@"
 }
 
@@ -49,5 +50,5 @@ fi
 
 gendoc::build
 gendoc::exec \
-    -api-dir "sigs.k8s.io/gateway-api/apis/" \
-    -out-file "${1}"
+    --source-path "${REPO}/apis/" \
+    --output-path "${1}"

hack/api-docs/gv_details.tpl

@@ -0,0 +1,19 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+
+## {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if $gv.Kinds  }}
+### Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

hack/api-docs/gv_list.tpl

@@ -0,0 +1,15 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+# API Reference
+
+<p>Packages:</p>
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}