hack: add docs generation/validation

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

.github/workflows/validate.yml

@@ -23,6 +23,7 @@ jobs:
         target:
           - lint
           - validate-vendor
+          - validate-docs
     steps:
       -
         name: Checkout

Makefile

@@ -23,12 +23,18 @@ test:
 validate-vendor:
 	./hack/validate-vendor
 	
-validate-all: lint test validate-vendor
+validate-docs:
+	./hack/validate-docs
+	
+validate-all: lint test validate-vendor validate-docs
 
 vendor:
 	./hack/update-vendor
 
+docs:
+	./hack/update-docs
+
 generate-authors:
 	./hack/generate-authors
 
-.PHONY: vendor lint shell binaries install binaries-cross validate-all generate-authors
+.PHONY: vendor lint shell binaries install binaries-cross validate-all generate-authors validate-docs docs

hack/dockerfiles/docs.Dockerfile

@@ -0,0 +1,29 @@
+# syntax = docker/dockerfile:1.2
+
+FROM golang:1.16-alpine AS docsgen
+WORKDIR /src
+RUN --mount=target=. \
+  --mount=target=/root/.cache,type=cache \
+  go build -mod=vendor -o /out/docsgen ./docs/docsgen
+
+FROM alpine AS gen
+RUN apk add --no-cache rsync git
+WORKDIR /src
+COPY --from=docsgen /out/docsgen /usr/bin
+RUN --mount=target=/context \
+  --mount=target=.,type=tmpfs,readwrite  \
+  rsync -a /context/. . && \
+  docsgen && \
+  mkdir /out && cp -r docs/reference /out
+
+FROM scratch AS update
+COPY --from=gen /out /out
+
+FROM gen AS validate
+RUN --mount=target=/context \
+  --mount=target=.,type=tmpfs,readwrite  \
+  rsync -a /context/. . && \
+  git add -A && \
+  rm -rf docs/reference/* && \
+  cp -rf /out/* ./docs/ && \
+  ./hack/validate-docs check

hack/update-docs

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+. $(dirname $0)/util
+set -eu
+
+output=$(mktemp -d -t buildx-output.XXXXXXXXXX)
+
+buildxCmd build \
+  --target "update" \
+  --output "type=local,dest=$output" \
+  --file "./hack/dockerfiles/docs.Dockerfile" \
+  .
+
+rm -rf ./docs/reference/*
+cp -R "$output"/out/* ./docs/
+rm -rf $output

hack/validate-docs

@@ -0,0 +1,29 @@
+#!/usr/bin/env sh
+set -eu
+
+case ${1:-} in
+  '')
+    . $(dirname $0)/util
+    buildxCmd build \
+      --target validate \
+      --file ./hack/dockerfiles/docs.Dockerfile \
+      .
+    ;;
+  check)
+    status="$(git status --porcelain -- docs/reference 2>/dev/null)"
+    diffs=$(echo "$status" | grep -v '^[RAD] ' || true)
+    if [ "$diffs" ]; then
+      {
+        set +x
+        echo 'The result of ./hack/update-docs differs'
+        echo
+        echo "$diffs"
+        echo
+        echo 'Please vendor your package with ./hack/update-docs'
+        echo
+      } >&2
+      exit 1
+    fi
+    echo 'Congratulations! All docs changes are done the right way.'
+    ;;
+esac