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 25, 2019 · 2b233fb · 2b233fb
1 parent 0f090a4
commit 2b233fb
Show file tree

Hide file tree

Showing 7 changed files with 2,360 additions and 2 deletions.
diff --git a/build/README.md b/build/README.md
@@ -352,7 +352,7 @@ The second step is to prepare your cluster for the Agones deployments. Run `make
 
 Now you're ready to begin the development/test cycle:
 - `make build` will build Agones
-- `make test` will run local tests
+- `make test` will run local tests, which includes `site-test` target
 - `make push` will push the Agones images to your image repository 
 - `make test-e2e` will run end-to-end tests in your cluster
 - `make install` will install/upgrade Agones into your cluster
@@ -412,6 +412,18 @@ Build the cpp sdk static and dynamic libraries (linux libraries only)
 #### `make test`
 Run the linter and tests
 
+#### `make site-server`
+Generate `https://agones.dev` website locally and host on `http://localhost:1313`
+
+#### `make site-test`
+Check the links in website
+
+#### `make gen-api-docs`
+Generate Agones CRD reference documentation [Agones CRD API reference](../site/content/en/docs/Reference/agones_crd_api_reference.html). Set `feature` shortcode with proper version automatically
+
+#### `make test-gen-api-docs`
+Verifies that there is no changes in generated [Agones CRD API reference](../site/content/en/docs/Reference/agones_crd_api_reference.html) compared to the current one (useful for CI)
+
 #### `make push`
 Pushes all built images up to the `$(REGISTRY)`
 

diff --git a/build/build-image/Dockerfile b/build/build-image/Dockerfile
@@ -123,6 +123,11 @@ RUN mkdir /tmp/hugo && \
 RUN curl -sL https://deb.nodesource.com/setup_11.x | bash - && \
     apt-get install -y nodejs
 
+# install API reference docs generator
+RUN 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
+
 # html checker
 RUN mkdir /tmp/htmltest && \
     wget -O /tmp/htmltest/htmltest.tar.gz https://github.com/wjdp/htmltest/releases/download/v0.10.1/htmltest_0.10.1_linux_amd64.tar.gz && \

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
+GEN_API_DOCS := docker run -e FILE="$(mount_path)/site/$(REL_PATH)" -e VERSION=${base_version} --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: expected_docs := $(site_path)/$(REL_PATH)
+test-gen-api-docs: ensure-build-image
+	cp $(expected_docs) /tmp/generated.html
+	sort /tmp/generated.html > /tmp/generated.html.sorted
+	$(GEN_API_DOCS)
+	sort $(expected_docs) > /tmp/result.sorted
+	diff -bB /tmp/result.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"
diff --git a/site/assets/templates/pkg.tpl b/site/assets/templates/pkg.tpl
@@ -0,0 +1,46 @@
+{{ define "packages" }}
+
+{{ with .packages}}
+<p>Packages:</p>
+<ul>
+    {{ range . }}
+    <li>
+        <a href="#{{- packageDisplayName . -}}">{{ packageDisplayName . }}</a>
+    </li>
+    {{ end }}
+</ul>
+{{ end}}
+
+{{ range .packages }}
+    <h2 id="{{- packageDisplayName . -}}">
+        {{- packageDisplayName . -}}
+    </h2>
+
+    {{ with .DocComments }}
+    <p>
+        {{ safe (renderComments .) }}
+    </p>
+    {{ end }}
+
+    Resource Types:
+    <ul>
+    {{- range (visibleTypes (sortedTypes .Types)) -}}
+        {{ if isExportedType . -}}
+        <li>
+            <a href="#{{ typeIdentifier . }}">{{ typeIdentifier . }}</a>
+        </li>
+        {{- end }}
+    {{- end -}}
+    </ul>
+
+    {{ range (visibleTypes (sortedTypes .Types))}}
+        {{ template "type" .  }}
+    {{ end }}
+    <hr/>
+{{ end }}
+
+<p><em>
+    Generated with <code>gen-crd-api-reference-docs</code>.
+</em></p>
+
+{{ end }}
diff --git a/site/content/en/docs/Guides/access-api.md b/site/content/en/docs/Guides/access-api.md
@@ -10,7 +10,11 @@ description: >
 ---
 
 Installing Agones creates several [Custom Resource Definitions (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources),
-which can be accessed and manipulated through the Kubernetes API.
+which can be accessed and manipulated through the Kubernetes API. 
+
+{{% feature publishVersion="0.9.0" %}}
+The detailed list of Agones CRDs with their parameters could be found here - [Agones CRD API Reference](../../reference/agones_crd_api_reference/).
+{{% /feature %}}
 
 Kubernetes has multiple [client libraries](https://kubernetes.io/docs/reference/using-api/client-libraries/), however,
 at time of writing, only