Add extended API docs generator

Add gen-crd-api-reference-docs utility into build-image, generate Agones CRD reference html document, map this doc to existent docs structure.
googleforgames · Mar 12, 2019 · 790ac8d · 790ac8d
1 parent b133e52
commit 790ac8d
Show file tree

Hide file tree

Showing 4 changed files with 2,243 additions and 0 deletions.
diff --git a/build/build-image/Dockerfile b/build/build-image/Dockerfile
@@ -103,6 +103,11 @@ RUN cargo install grpcio-compiler --vers 0.3.0
 RUN go get -u github.com/golang/dep/cmd/dep && \
     go get -u golang.org/x/tools/cmd/goimports
 
+# install API reference docs generator
+RUN export GO111MODULE=on && mkdir -p /go/src/github.com/ahmetb && \
+    cd /go/src/github.com/ahmetb && git clone https://github.com/ahmetb/gen-crd-api-reference-docs && \
+    cd ./gen-crd-api-reference-docs && go build
+
 # install golang-ci linter
 RUN curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | sh -s -- -b $GOPATH/bin v1.15.0
 

diff --git a/build/includes/website.mk b/build/includes/website.mk
@@ -24,6 +24,22 @@
 # Website targets
 #
 
+REL_PATH := content/en/docs/Reference/agones_crd_api_reference.html
+API_DOC_PATH := "$(mount_path)/site/$(REL_PATH)"
+GEN_API_DOCS ?= docker run -e FILE=$(API_DOC_PATH) --rm -i $(common_mounts) $(build_tag) bash -c "/go/src/agones.dev/agones/site/gen-api-docs.sh"
+
+# generate Agones CRD reference docs
+gen-api-docs: ensure-build-image
+	$(GEN_API_DOCS)
+
+# test generated Agones CRD reference docs
+test-gen-api-docs: ensure-build-image
+	cp $(agones_path)/site/$(REL_PATH) /tmp/generated.html
+	sort /tmp/generated.html > /tmp/generated.html.sorted
+	$(GEN_API_DOCS)
+	sort $(agones_path)/site/$(REL_PATH) > $(agones_path)/site/$(REL_PATH).sorted
+	diff -bB $(agones_path)/site/$(REL_PATH).sorted /tmp/generated.html.sorted
+
 # generate the latest website
 site-server: ARGS ?=-F
 site-server: ENV ?= RELEASE_VERSION="$(base_version)" RELEASE_BRANCH=master
@@ -59,6 +75,7 @@ site-deploy-preview: site-static-preview
 
 site-test:
 	# generate actual html and run test against - provides a more accurate tests
+	$(MAKE) test-gen-api-docs
 	$(MAKE) site-static-preview
 	docker run --rm -t -e "TERM=xterm-256color" $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
 		"mkdir -p /tmp/website && cp -r $(mount_path)/site/public /tmp/website/site && htmltest -c $(mount_path)/site/htmltest.yaml /tmp/website"