From a7fa31d56e0105b35cfaf911d53adef989f3d81e Mon Sep 17 00:00:00 2001 From: Charlie Egan Date: Thu, 5 Oct 2023 09:28:40 +0100 Subject: [PATCH] [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 --- .gitignore | 1 + docs/Makefile | 10 +++------- docs/website/layouts/shortcodes/builtin-table.html | 10 +++++----- docs/website/layouts/shortcodes/builtin-tags.html | 9 +++++---- docs/website/scripts/load-docs.sh | 10 ++++++++++ 5 files changed, 24 insertions(+), 16 deletions(-) diff --git a/.gitignore b/.gitignore index e6429ce649..c4660c508d 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,4 @@ man # generated when running local website build docs/website/.hugo_build.lock +docs/website/data/versions diff --git a/docs/Makefile b/docs/Makefile index ac328c3ec3..873e1c7434 100644 --- a/docs/Makefile +++ b/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 ###################################################### # diff --git a/docs/website/layouts/shortcodes/builtin-table.html b/docs/website/layouts/shortcodes/builtin-table.html index a07ee24f39..19af6a55ba 100644 --- a/docs/website/layouts/shortcodes/builtin-table.html +++ b/docs/website/layouts/shortcodes/builtin-table.html @@ -12,12 +12,13 @@ {{- end -}}

{{ $title | title }}

+ +{{- $bimd := index (index site.Data.versions $version) "builtin_metadata" }} - {{- 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 }} {{- end }} - {{- end }} -
@@ -95,6 +96,5 @@
\ No newline at end of file + diff --git a/docs/website/layouts/shortcodes/builtin-tags.html b/docs/website/layouts/shortcodes/builtin-tags.html index 95ff727c58..1ef1cb4854 100644 --- a/docs/website/layouts/shortcodes/builtin-tags.html +++ b/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 }} +
{{- if eq $metadata.introduced $version }} New @@ -22,4 +23,4 @@ {{- else -}} SDK-dependent {{- end -}} -
\ No newline at end of file + diff --git a/docs/website/scripts/load-docs.sh b/docs/website/scripts/load-docs.sh index ab84fd4962..82ba3daede 100755 --- a/docs/website/scripts/load-docs.sh +++ b/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