[docs] Fix unversioned built-in docs issue (#6274)

Fixes https://github.com/open-policy-agent/opa/issues/6269

This fixes the issue by using the builtin_metadata.json file from each
version, the assumption that docs content that depends on the data
doesn't exist before this file was introduced.

I have removed the 'available' check since we haven't consistently
updated the file in the past, e.g.

* https://github.com/open-policy-agent/opa/blob/v0.41.0/builtin_metadata.json#L12710
* https://github.com/open-policy-agent/opa/blob/v0.57.0/builtin_metadata.json#L563

These examples show that sometimes the current version is included,
other times the file is updated after the release.

Video showing the correct content being displayed for various versions:

https://github.com/open-policy-agent/opa/assets/1774239/abf1af7d-9c59-4223-a019-c73d7550b322

To locally test this:

```
git clean -dfx
cd docs
make generate hugo-production-build
hugo server --source website --contentDir generated --ignoreCache --minify
```

Signed-off-by: Charlie Egan <charlie@styra.com>

.gitignore

@@ -37,3 +37,4 @@ man
 
 # generated when running local website build
 docs/website/.hugo_build.lock
+docs/website/data/versions

docs/Makefile

@@ -20,20 +20,16 @@ generate-cli-docs:
 	$(CURDIR)/../build/gen-cli-docs.sh "$(CURDIR)/content"
 
 .PHONY: generate
-generate: generate-cli-docs copy-builtin-metadata copy-hugo-static-content
+generate: generate-cli-docs copy-hugo-static-content
 	$(CURDIR)/website/scripts/load-docs.sh
 
-.PHONY: copy-builtin-metadata
-copy-builtin-metadata:
-	cp -v $(CURDIR)/../builtin_metadata.json $(CURDIR)/website/data/builtin_metadata.json
-
 .PHONY: copy-hugo-static-content
 copy-hugo-static-content:
 	mkdir -p $(CURDIR)/website/generated/
 	cp -r $(CURDIR)/website/content/* $(CURDIR)/website/generated/
 
 .PHONY: dev-generate
-dev-generate: generate-cli-docs copy-builtin-metadata copy-hugo-static-content
+dev-generate: generate-cli-docs copy-hugo-static-content
 	DEV=true $(CURDIR)/website/scripts/load-docs.sh
 
 # The website has some npm dependencies saved in ./website/node_modules
@@ -63,7 +59,7 @@ serve-remote: production-build
 	cd $(CURDIR)/.. && netlify deploy
 
 .PHONY: dev-build
-dev-build: clean dev-generate copy-builtin-metadata hugo-production-build live-blocks-inject
+dev-build: clean dev-generate hugo-production-build live-blocks-inject
 
 ######################################################
 #

docs/website/layouts/shortcodes/builtin-table.html

@@ -12,12 +12,13 @@
 {{- end -}}
 
 <h3 id={{ $id }}>{{ $title | title }}</h3>
+
+{{- $bimd := index (index site.Data.versions $version) "builtin_metadata" }}
 <table class="table bi-cat is-hoverable">
     <tbody>
-    {{- range $name := index site.Data.builtin_metadata._categories $cat }}
+    {{- range $name := index $bimd._categories $cat }}
     {{- $anchor := anchorize (printf "builtin-%s-%s" $cat $name) }}
-    {{- $bi := index site.Data.builtin_metadata $name }}
-    {{- if in $bi.available $version }}
+    {{- $bi := index $bimd $name }}
     <tr id="{{ $anchor }}">
         <th>
             <a class="self-link" href="#{{ $anchor }}">
@@ -95,6 +96,5 @@
         </td>
     </tr>
     {{- end }}
-    {{- end }}
     </tbody>
-</table>
+</table>

docs/website/layouts/shortcodes/builtin-tags.html

@@ -1,11 +1,12 @@
 {{- $name := .Get 0 -}}
-{{- $metadata := index site.Data.builtin_metadata $name }}
-
 {{- $version := index (split $.Page.File.Path "/") 1 -}}
 {{- if (eq $version "latest") -}}
-{{- $version = index site.Data.releases 1 -}}
+  {{- $version = index site.Data.releases 1 -}}
 {{- end -}}
 
+{{- $bimd := index (index site.Data.versions $version) "builtin_metadata" }}
+{{- $metadata := index $bimd $name }}
+
 <div class="tags">
     {{- if eq $metadata.introduced $version }}
         <span class="tag is-primary">New</span>
@@ -22,4 +23,4 @@
     {{- else -}}
         <span class="tag is-warning">SDK-dependent</span>
     {{- end -}}
-</div>
+</div>

docs/website/scripts/load-docs.sh

@@ -88,13 +88,18 @@ fi
 
 for release in "${RELEASES[@]}"; do
     version_docs_dir=${ROOT_DIR}/docs/website/generated/docs/${release}
+    version_builtin_metadata_dir=${ROOT_DIR}/docs/website/data/versions/${release}
     mkdir -p ${version_docs_dir}
+    mkdir -p ${version_builtin_metadata_dir}
 
     echo "Checking out release ${release}"
 
     # Don't error if the checkout fails
     set +e
     git archive --format=tar ${release} content | tar x -C ${version_docs_dir} --strip-components=1
+    cd ${ROOT_DIR}
+    git archive --format=tar ${release} builtin_metadata.json | tar x -C ${version_builtin_metadata_dir}
+    cd -
     errc=$?
     set -e
 
@@ -117,6 +122,11 @@ echo "- edge" >> ${RELEASES_YAML_FILE}
 mkdir -p ${ROOT_DIR}/docs/website/generated/docs
 ln -s ../../../content ${ROOT_DIR}/docs/website/generated/docs/edge
 
+# this is a special case for the "edge" version, we must use the builtin_metadata.json from main here
+# otherwise there are no matches when building the tables.
+mkdir -p ${ROOT_DIR}/docs/website/data/versions/edge
+cp ${ROOT_DIR}/builtin_metadata.json ${ROOT_DIR}/docs/website/data/versions/edge/builtin_metadata.json
+
 # Create a "latest" version from the latest semver found
 if [[ ${DEV} == "" ]]; then
     cp -r ${ROOT_DIR}/docs/website/generated/docs/${RELEASES[0]} ${ROOT_DIR}/docs/website/generated/docs/latest