Moving reference docs gen to elastic/crd-ref-docs

Author: robscott

.github/dependabot.yml

@@ -54,7 +54,7 @@ updates:
 
   # Dependencies listed in requirements.txt
   - package-ecosystem: "pip"
-    directory: "/"
+    directory: "/hack/mkdocs/image"
     schedule:
       interval: "weekly"
     labels:

.gitignore

@@ -56,3 +56,4 @@ go.work.sum
 /cache
 .venv/
 release/
+site-src/reference/spec.md

Makefile

@@ -91,7 +91,7 @@ test.crds-validation:
 .PHONY: conformance
 conformance:
 	go test ${GO_TEST_FLAGS} -v ./conformance -run TestConformance -args ${CONFORMANCE_FLAGS}
-	
+
 # Install CRD's and example resources to a preexisting cluster.
 .PHONY: install
 install: crd example
@@ -159,14 +159,27 @@ image.multiarch.setup: image.buildx.verify
 release-staging: image.multiarch.setup
 	hack/build-and-push.sh
 
-# Generate a virtualenv install, which is useful for hacking on the
-# docs since it installs mkdocs and all the right dependencies.
-#
-# On Ubuntu, this requires the python3-venv package.
-virtualenv: .venv
-.venv: requirements.txt
-	@echo Creating a virtualenv in $@"... "
-	@python3 -m venv $@ || (rm -rf $@ && exit 1)
-	@echo Installing packages in $@"... "
-	@$@/bin/python3 -m pip install -q -r requirements.txt || (rm -rf $@ && exit 1)
-	@echo To enter the virtualenv type \"source $@/bin/activate\",  to exit type \"deactivate\"
+# Docs
+
+.PHONY: build-docs
+build-docs:
+	docker build --pull -t gaie/mkdocs hack/mkdocs/image
+	docker run --rm -v ${PWD}:/docs gaie/mkdocs build
+
+.PHONY: build-docs-netlify
+build-docs-netlify: api-ref-docs
+	pip install -r hack/mkdocs/image/requirements.txt
+	python -m mkdocs build
+
+.PHONY: live-docs
+live-docs:
+	docker build -t gw/mkdocs hack/mkdocs/image
+	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gw/mkdocs
+
+.PHONY: api-ref-docs
+api-ref-docs:
+	crd-ref-docs \
+		--source-path=${PWD}/apis \
+		--config=crd-ref-docs.yaml \
+		--renderer=markdown \
+		--output-path=${PWD}/site-src/reference/spec.md

crd-ref-docs.yaml

@@ -0,0 +1,14 @@
+# This file contains configuration for our reference docs generation. For more
+# information about the possible configuration, refer to
+# https://github.com/elastic/crd-ref-docs.
+
+processor:
+  ignoreTypes:
+    - "()List$"
+  # RE2 regular expressions describing type fields that should be excluded from the generated documentation.
+  ignoreFields:
+    - "TypeMeta$"
+
+render:
+  # Version of Kubernetes to use when generating links to Kubernetes API documentation.
+  kubernetesVersion: 1.32

go.mod

@@ -3,7 +3,7 @@ module sigs.k8s.io/gateway-api
 go 1.24.0
 
 require (
-	github.com/ahmetb/gen-crd-api-reference-docs v0.3.0
+	github.com/elastic/crd-ref-docs v0.1.0
 	github.com/miekg/dns v1.1.63
 	github.com/stretchr/testify v1.10.0
 	golang.org/x/net v0.35.0

hack/mkdocs/image/Dockerfile

@@ -0,0 +1,26 @@
+# Copyright 2019 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+FROM python:3.12
+
+COPY requirements.txt /requirements.txt
+RUN pip install -r /requirements.txt
+
+WORKDIR /docs
+
+EXPOSE 3000
+
+COPY entrypoint.sh /
+
+ENTRYPOINT ["/entrypoint.sh"]

hack/mkdocs/image/entrypoint.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+# Copyright 2019 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+
+CMD=$1
+
+if [ "$CMD" == "build" ];
+then
+  mkdocs build
+  exit 0;
+fi
+
+mkdocs serve --dev-addr=0.0.0.0:3000 --livereload

requirements.txt hack/mkdocs/image/requirements.txt

@@ -20,4 +20,4 @@ pymdown-extensions==10.14.3
 PyYAML==6.0.2
 six==1.17.0
 tabulate==0.9.0
-tornado==6.4.2
+tornado==6.4.2

netlify.toml

@@ -1,6 +1,6 @@
 # Netlify build instructions
 [build]
-    command = "make docs"
+    command = "make build-docs-netlify"
     publish = "site"
 [build.environment]
     PYTHON_VERSION = "3.12"

site-src/reference/spec.md

@@ -23,7 +23,7 @@ limitations under the License.
 package tools
 
 import (
-	_ "github.com/ahmetb/gen-crd-api-reference-docs"
+	_ "github.com/elastic/crd-ref-docs"
 	_ "google.golang.org/grpc/cmd/protoc-gen-go-grpc"
 	_ "google.golang.org/protobuf/cmd/protoc-gen-go"
 	_ "k8s.io/code-generator/cmd/client-gen"