[GSoD'20] Update how the Kubernetes website serves API references

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "themes/docsy"]
 	path = themes/docsy
 	url = https://github.com/google/docsy.git
+[submodule "api-ref-generator"]
+	path = api-ref-generator
+	url = https://github.com/kubernetes-sigs/reference-docs

Dockerfile

@@ -4,7 +4,7 @@
 # change is that the Hugo version is now an overridable argument rather than a fixed
 # environment variable.
 
-FROM alpine:latest
+FROM golang:1.15-alpine
 
 LABEL maintainer="Luc Perkins <[email protected]>"
 

Makefile

@@ -85,3 +85,10 @@ docker-internal-linkcheck:
 container-internal-linkcheck: link-checker-image-pull
 	$(CONTAINER_RUN) $(CONTAINER_IMAGE) hugo --config config.toml,linkcheck-config.toml --buildFuture
 	$(CONTAINER_ENGINE) run --mount type=bind,source=$(CURDIR),target=/test --rm wjdp/htmltest htmltest
+
+clean-api-reference: ## Clean all directories in API reference directory, preserve _index.md
+	rm -rf content/en/docs/reference/kubernetes-api/*/
+
+api-reference: clean-api-reference ## Build the API reference pages. go needed
+	cd api-ref-generator/gen-resourcesdocs && \
+		go run cmd/main.go kwebsite --config-dir config/v1.20/ --file api/v1.20/swagger.json --output-dir ../../content/en/docs/reference/kubernetes-api --templates templates

README.md

@@ -59,6 +59,49 @@ make serve
 
 This will start the local Hugo server on port 1313. Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
 
+## Building the API reference pages
+
+The API reference pages located in `content/en/docs/reference/kubernetes-api` are built from the Swagger specification, using https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs.
+
+To update the reference pages for a new Kubernetes release (replace v1.20 in the following examples with the release to update to):
+
+1. Pull the `kubernetes-resources-reference` submodule:
+
+```
+git submodule update --init --recursive --depth 1
+```
+
+2. Create a new API revision into the submodule, and add the Swagger specification:
+
+```
+mkdir api-ref-generator/gen-resourcesdocs/api/v1.20
+curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-generator/gen-resourcesdocs/api/v1.20/swagger.json
+```
+
+3. Copy the table of contents and fields configuration for the new release from a previous one:
+
+```
+mkdir api-ref-generator/gen-resourcesdocs/api/v1.20
+cp api-ref-generator/gen-resourcesdocs/api/v1.19/* api-ref-generator/gen-resourcesdocs/api/v1.20/
+```
+
+4. Adapt the files `toc.yaml` and `fields.yaml` to reflect the changes between the two releases
+
+5. Next, build the pages:
+
+```
+make api-reference
+```
+
+You can test the results locally by making and serving the site from a container image:
+
+```
+make container-image
+make container-serve
+```
+
+6. When all changes of the new contract are reflected into the configuration files `toc.yaml` and `fields.yaml`, create a Pull Request with the newly generated API reference pages.
+
 ## Troubleshooting
 ### error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version
 

content/en/docs/reference/_index.md

@@ -18,7 +18,8 @@ This section of the Kubernetes documentation contains references.
 
 ## API Reference
 
-* [API Reference for Kubernetes {{< param "version" >}}](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
+* [Kubernetes API Reference](/docs/reference/kubernetes-api/)
+* [One-page API Reference for Kubernetes {{< param "version" >}}](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
 * [Using The Kubernetes API](/docs/reference/using-api/) - overview of the API for Kubernetes.
 
 ## API Client Libraries

content/en/docs/reference/kubernetes-api/_index.md

@@ -1,4 +1,8 @@
 ---
-title: API Reference
+title: "Kubernetes API"
 weight: 30
 ---
+
+<!-- overview -->
+
+{{< glossary_definition prepend="Kubernetes' API is" term_id="kubernetes-api" length="all" >}}

content/en/docs/reference/kubernetes-api/authentication-resources/_index.md

@@ -0,0 +1,4 @@
+---
+title: "Authentication Resources"
+weight: 4
+---