From df1b34898bea812b197ca7404b29094f740df26c Mon Sep 17 00:00:00 2001
From: Jack Baldry <jack.baldry@grafana.com>
Date: Fri, 14 Apr 2023 20:13:26 +0100
Subject: [PATCH] Use centralized make-docs script from Writers' Toolkit
 (#9126)

- Adds ability to build multiple projects simultaneously using, for
example, `make docs PROJECTS='grafana grafana-cloud'`.
- Adds `make doc-validator` which runs
[`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator)
on all documentation.

Using a centralized script will help ensure consistency in workflow
across all projects.

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
---
 .gitignore        |  1 +
 docs/Makefile     | 26 +++++---------
 docs/docs.mk      | 87 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/variables.mk |  2 ++
 4 files changed, 99 insertions(+), 17 deletions(-)
 create mode 100644 docs/docs.mk
 create mode 100644 docs/variables.mk

diff --git a/.gitignore b/.gitignore
index a0cc2550cb204..3926dcad0207c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,3 +51,4 @@ pkg/loki/wal
 
 # nix
 result
+/docs/make-docs
diff --git a/docs/Makefile b/docs/Makefile
index e3a60c3698159..016b74d291ceb 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,22 +1,14 @@
-PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
-IMAGE := grafana/docs-base:latest
-BUILD_IN_CONTAINER ?= true
-
-.PHONY: pull
-pull:
-	$(PODMAN) pull ${IMAGE}
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
 
-.PHONY: docs
-docs: pull
-	$(PODMAN) run  --rm -it -v ${PWD}/sources:/hugo/content/docs/loki/latest -p 3002:3002 $(IMAGE)
+include docs.mk
 
-.PHONY: docs-next
-docs-next: pull
-	$(PODMAN) run  --rm -it -v ${PWD}/sources:/hugo/content/docs/loki/next -p 3002:3002 $(IMAGE)
-
-.PHONY: docs-test
-docs-test: pull
-	$(PODMAN) run --rm -it -v ${PWD}/sources:/hugo/content/docs/loki/latest -p 3002:3002 $(IMAGE) /bin/bash -c 'make prod'
+PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
+BUILD_IN_CONTAINER ?= true
 
 sources/installation/helm/reference.md: ../production/helm/loki/reference.md.gotmpl
 ifeq ($(BUILD_IN_CONTAINER),true)
diff --git a/docs/docs.mk b/docs/docs.mk
new file mode 100644
index 0000000000000..f556b52f47d3e
--- /dev/null
+++ b/docs/docs.mk
@@ -0,0 +1,87 @@
+include variables.mk
+-include variables.mk.local
+
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
+
+.DEFAULT_GOAL: help
+
+# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
+.PHONY: help
+help: ## Display this help.
+help:
+	@awk 'BEGIN {FS = ": ##"; printf "Usage:\n  make <target>\n\nTargets:\n"} /^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf "  %-45s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+GIT_ROOT := $(shell git rev-parse --show-toplevel)
+
+PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
+
+ifeq ($(PROJECTS),)
+$(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)))
+
+# Name for the container.
+export DOCS_CONTAINER := $(PRIMARY_PROJECT)-docs
+
+# Host port to publish container port to.
+export DOCS_HOST_PORT := 3002
+
+# Container image used to perform Hugo build.
+export DOCS_IMAGE := grafana/docs-base:latest
+
+# Container image used for doc-validator linting.
+export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest
+
+# PATH-like list of directories within which to find projects.
+# If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
+export REPOS_PATH := $(realpath $(GIT_ROOT)/..)
+
+# How to treat Hugo relref errors.
+export HUGO_REFLINKSERRORLEVEL := WARNING
+
+.PHONY: docs-rm
+docs-rm: ## Remove the docs container.
+	$(PODMAN) rm -f $(DOCS_CONTAINER)
+
+.PHONY: docs-pull
+docs-pull: ## Pull documentation base image.
+	$(PODMAN) pull $(DOCS_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
+
+.PHONY: docs
+docs: ## Serve documentation locally.
+docs: docs-pull make-docs
+	$(PWD)/make-docs $(PROJECTS)
+
+.PHONY: docs-no-pull
+docs-no-pull: ## Serve documentation locally without pulling the latest docs-base image.
+docs-no-pull: make-docs
+	$(PWD)/make-docs $(PROJECTS)
+
+.PHONY: docs-debug
+docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
+docs-debug: make-docs
+	WEBSITE_EXEC='hugo server --debug' $(PWD)/make-docs $(PROJECTS)
+
+.PHONY: doc-validator
+doc-validator: ## Run docs-validator on the entire docs folder.
+	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/%:
+	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) DOC_VALIDATOR_INCLUDE=$(subst doc-validator/,,$@) $(PWD)/make-docs $(PROJECTS)
+
+docs.mk: ## Fetch the latest version of this Makefile from Writers' Toolkit.
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
diff --git a/docs/variables.mk b/docs/variables.mk
new file mode 100644
index 0000000000000..d3bf4fa1cb01d
--- /dev/null
+++ b/docs/variables.mk
@@ -0,0 +1,2 @@
+# List of projects to provide to the make-docs script.
+PROJECTS = loki