Implement multi version for apiref (#4190)

Author: rikatz

.gitignore

@@ -51,6 +51,7 @@ Session.vim
 .*.timestamp
 /site
 go.work.sum
+/tmp
 
 /cache
 .venv/

Makefile

@@ -182,7 +182,6 @@ build-docs:
 
 .PHONY: build-docs-netlify
 build-docs-netlify: api-ref-docs
-	hack/mkdocs/generate.sh
 	pip install -r hack/mkdocs/image/requirements.txt
 	python -m mkdocs build
 

RELEASE.md

@@ -74,6 +74,8 @@ The following steps must be done by one of the [Gateway API maintainers][gateway
   Attach these files to the GitHub release.
 - Update the `README.md` and `site-src/guides/index.md` files to point links and examples to the new release.
 - Update the implementation table path (`nav.Implementations.Comparison`) in the nav of `mkdocs.yml` to point to the latest release file (for example Implementation Comparison points to `implementation-table-v1.2.0.md`). Add the now past version under `Past Version Comparisons`, and edit the text blurb in `mkdocs-generate-conformance.py` to also reflect the added past version.
+- Update `hack/mkdocs/generate.sh` and add the new `release-x.x` to the array of releases.
+- Update `nav.yml.tmpl` and add the new release to the `API specification` field. Execute `./hack/update-mkdocs-nav.sh` after that.
 
 #### For an **RC** release:
 - Update `pkg/consts/consts.go` with the new semver tag (like `v1.2.0-rc1`) and any updates to the API review URL.

hack/mkdocs/generate.sh

@@ -24,23 +24,41 @@ GOPATH=${GOPATH:-$(go env GOPATH)}
 # have to manually default it.
 GOBIN=${GOBIN:-$(go env GOBIN)}
 GOBIN=${GOBIN:-${GOPATH}/bin}
+REMOTE=${REMOTE:-origin}
 
 readonly GOTOOL="go tool"
 
 echo $GOBIN
 
 go install github.com/elastic/crd-ref-docs
+declare -a arr=(
+    "release-1.3"
+    "release-1.4"
+    "main"
+)
 
-$GOTOOL crd-ref-docs \
-    --source-path=${PWD}/apis \
-    --config=crd-ref-docs.yaml \
-    --templates-dir=${PWD}/hack/crd-ref-templates/ \
-    --renderer=markdown \
-    --output-path=${PWD}/site-src/reference/spec.md
-
-$GOTOOL crd-ref-docs \
-    --source-path=${PWD}/apisx \
-    --config=crd-ref-docs.yaml \
-    --templates-dir=${PWD}/hack/crd-ref-templates/ \
-    --renderer=markdown \
-    --output-path=${PWD}/site-src/reference/specx.md
+mkdir -p ${PWD}/tmp
+
+for i in "${arr[@]}"; do
+    tmpdir=$(mktemp -d --tmpdir=${PWD}/tmp)
+    
+    git fetch ${REMOTE} ${i}
+	git --work-tree=${tmpdir} checkout ${REMOTE}/${i} -- apis apisx
+	
+    docpath=${i#"release-"}
+	mkdir -p "${PWD}/site-src/reference/${docpath}"
+
+    $GOTOOL crd-ref-docs \
+        --source-path=${tmpdir}/apis \
+        --config=crd-ref-docs.yaml \
+        --templates-dir=${PWD}/hack/crd-ref-templates/ \
+        --renderer=markdown \
+        --output-path=${PWD}/site-src/reference/${docpath}/spec.md
+
+    $GOTOOL crd-ref-docs \
+        --source-path=${tmpdir}/apisx \
+        --config=crd-ref-docs.yaml \
+        --templates-dir=${PWD}/hack/crd-ref-templates/ \
+        --renderer=markdown \
+        --output-path=${PWD}/site-src/reference/${docpath}/specx.md
+done

nav.yml

@@ -56,8 +56,15 @@ nav:
         - BackendTrafficPolicy: api-types/backendtrafficpolicy.md
       - ReferenceGrant: api-types/referencegrant.md
     - API specification:
-      - Standard: reference/spec.md
-      - Experimental: reference/specx.md
+      - Development:
+        - Standard: reference/main/spec.md
+        - Experimental: reference/main/specx.md
+      - v1.4:
+        - Standard: reference/1.4/spec.md
+        - Experimental: reference/1.4/specx.md
+      - v1.3:
+        - Standard: reference/1.3/spec.md
+        - Experimental: reference/1.3/specx.md
     - Policy Attachment: reference/policy-attachment.md
   - Enhancements:
     - Overview: geps/overview.md

nav.yml.tmpl

@@ -56,8 +56,15 @@ nav:
         - BackendTrafficPolicy: api-types/backendtrafficpolicy.md
       - ReferenceGrant: api-types/referencegrant.md
     - API specification:
-      - Standard: reference/spec.md
-      - Experimental: reference/specx.md
+      - Development:
+        - Standard: reference/main/spec.md
+        - Experimental: reference/main/specx.md
+      - v1.4:
+        - Standard: reference/1.4/spec.md
+        - Experimental: reference/1.4/specx.md
+      - v1.3:
+        - Standard: reference/1.3/spec.md
+        - Experimental: reference/1.3/specx.md
     - Policy Attachment: reference/policy-attachment.md
   - Enhancements:
     - Overview: geps/overview.md