From 2b92aeeab81180a8b1e302a9d2e96b32fe8c4f7b Mon Sep 17 00:00:00 2001
From: Jack Baldry <jack.baldry@grafana.com>
Date: Mon, 1 May 2023 09:41:10 +0100
Subject: [PATCH] Update centralized make-docs procedure (#9287)

**What this PR does / why we need it**:
Supports Ubuntu Snap based Docker installations by using TMPDIR instead
of an explicit tempfile.

Because Ubuntu Snap packages have access to only the user's home
directory, users must specify something like `TMPDIR="$(mktemp -d -q
~/.make-docs.XXXXX)"` in order to be able to run `make docs`.

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
---
 docs/docs.mk   | 15 ++++++++++-----
 docs/make-docs | 20 +++++++++++++++-----
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/docs/docs.mk b/docs/docs.mk
index 61c73fc6ed..7c7072085b 100644
--- a/docs/docs.mk
+++ b/docs/docs.mk
@@ -30,7 +30,7 @@ $(error "PROJECTS variable must be defined in variables.mk")
 endif
 
 # First project is considered the primary one used for doc-validator.
-PRIMARY_PROJECT := $(firstword $(subst /,-,$(PROJECTS)))
+PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS)))))
 
 # Name for the container.
 ifeq ($(origin DOCS_CONTAINER), undefined)
@@ -73,8 +73,10 @@ docs-pull: ## Pull documentation base image.
 
 make-docs: ## Fetch the latest make-docs script.
 make-docs:
-	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/scripts/make-docs
-	chmod +x make-docs
+	if [[ ! -f "$(PWD)/make-docs" ]]; then
+		echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2
+		exit 1
+	fi
 
 .PHONY: docs
 docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. See also `docs-no-pull`.
@@ -93,13 +95,16 @@ docs-debug: make-docs
 
 .PHONY: doc-validator
 doc-validator: ## Run docs-validator on the entire docs folder.
+doc-validator: make-docs
 	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(PWD)/make-docs $(PROJECTS)
 
 .PHONY: doc-validator/%
 doc-validator/%: ## Run doc-validator on a specific path. To lint the path /docs/sources/administration, run 'make doc-validator/administration'.
-doc-validator/%:
+doc-validator/%: make-docs
 	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) DOC_VALIDATOR_INCLUDE=$(subst doc-validator/,,$@) $(PWD)/make-docs $(PROJECTS)
 
 .PHONY: update
-update: ## Fetch the latest version of this Makefile from Writers' Toolkit.
+update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
 	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
+	chmod +x make-docs
diff --git a/docs/make-docs b/docs/make-docs
index 41e3957f67..90fc154cf9 100755
--- a/docs/make-docs
+++ b/docs/make-docs
@@ -1,5 +1,5 @@
 #!/bin/sh
-# Source of this file is https://github.com/grafana/technical-documentation/scripts/make-docs.
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs.
 
 set -ef
 
@@ -11,6 +11,8 @@ readonly DOC_VALIDATOR_INCLUDE="${DOC_VALIDATOR_INCLUDE:-.+\.md$}"
 
 readonly HUGO_REFLINKSERRORLEVEL="${HUGO_REFLINKSERRORLEVEL:-WARNING}"
 readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server}"
+# If set, the docs-base image will run a prebuild script that sets up Hugo mounts.
+readonly WEBSITE_MOUNTS="${WEBSITE_MOUNTS:-}"
 
 PODMAN="$(if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)"
 
@@ -67,6 +69,7 @@ VERSIONS_as_code='UNVERSIONED'
 VERSIONS_grafana_cloud='UNVERSIONED'
 VERSIONS_grafana_cloud_k6='UNVERSIONED'
 VERSIONS_opentelemetry='UNVERSIONED'
+VERSIONS_technical_documentation='UNVERSIONED'
 VERSIONS_writers_toolkit='UNVERSIONED'
 
 PATHS_helm_charts_mimir_distributed='docs/sources/helm-charts/mimir-distributed'
@@ -190,6 +193,7 @@ POSIX_HERESTRING
 
   echo "ERRR: could not find project '${_repo}' in any of the paths in REPOS_PATH '${REPOS_PATH}'." >&2
   echo "NOTE: you must have a checkout of the project '${_repo}' at '${REPOS_PATH##:*}/${_repo}'." >&2
+  echo "NOTE: if you have cloned the repository into a directory with a different name, consider changing it to ${_repo}." >&2
   unset _path _repo
   exit 1
 }
@@ -292,7 +296,6 @@ IFS=':' read -r image _ <<POSIX_HERESTRING
 ${DOCS_IMAGE}
 POSIX_HERESTRING
 
-echo "${image}" >&2
 if [ "${image}" = "grafana/doc-validator" ]; then
   echo
   "${PODMAN}" run \
@@ -310,17 +313,23 @@ if [ "${image}" = "grafana/doc-validator" ]; then
     "$(proj_canonical "$(new_proj "$1")")"
 else
 
-  cat <<EOF >/tmp/make-docs-entrypoint
+  tempfile="$(mktemp -t make-docs.XXX)"
+  cat <<EOF >"${tempfile}"
 #!/usr/bin/env bash
 for redirect in ${redirects}; do
   IFS='^' read -r path ver <<<"\${redirect}"
   echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\n---\\n" > "\${path/\${ver}/_index.md}"
+
 done
 
+if [[ -n "${WEBSITE_MOUNTS}" ]]; then
+  unset WEBSITE_SKIP_MOUNTS
+fi
+
 ${WEBSITE_EXEC}
 EOF
-  chmod +x /tmp/make-docs-entrypoint
-  volumes="${volumes} --volume=/tmp/make-docs-entrypoint:/entrypoint"
+  chmod +x "${tempfile}"
+  volumes="${volumes} --volume=$(realpath "${tempfile}"):/entrypoint"
   readonly volumes
 
   echo
@@ -343,6 +352,7 @@ POSIX_HERESTRING
     --name "${DOCS_CONTAINER}" \
     --platform linux/amd64 \
     --publish "${DOCS_HOST_PORT}:3002" \
+    --publish "3003:3003" \
     --rm \
     --tty \
     ${volumes} \