Merge pull request #1386 from grafana/jdb/2023-10-grafana-com

Publish documentation to grafana.com website

.eslintignore

@@ -1,6 +1,7 @@
 .cache/
 public/
 node_modules/
+docs/sources/
 docs/sources/get-started/run-cloud-tests-from-the-CLI.md
 docs/sources/get-started/run-your-first-tests.md
 CONTRIBUTING_FILE_FORMAT.md

.github/workflows/doc-validator.yml

@@ -1,24 +1,28 @@
-name: doc-validator
+name: Validate documentation
 on:
   pull_request:
-    paths:
-      - "docs/sources/**"
-
+    paths: ["docs/sources/**"]
+  workflow_dispatch:
 jobs:
   doc-validator:
-    runs-on: ubuntu-latest
-    container:
-      image: grafana/doc-validator:v1.9.0
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v3
-      - name: Run doc-validator tool
-        run: doc-validator --skip-image-validation ./docs/sources /docs/k6
-  test:
     runs-on: "ubuntu-latest"
+    container:
+      image: "grafana/doc-validator:v4.0.0"
     steps:
-      - name: "Check out code"
-        uses: "actions/checkout@v1"
-      - name: "Build Website"
-        run: |
-          docker run -v ${PWD}/docs/sources:/hugo/content/docs/k6 --rm grafana/docs-base:latest /bin/bash -c 'make hugo'
+      - name: "Checkout code"
+        uses: "actions/checkout@v3"
+      - name: "Run doc-validator tool"
+        run: >
+          doc-validator
+          '--skip-checks=^image.+$'
+          docs/sources
+          /docs/k6
+          | grep -v "The 'description' parameter in the front matter must be present."
+          | reviewdog
+          -f=rdjsonl
+          --fail-on-error
+          --filter-mode=nofilter
+          --name=doc-validator
+          --reporter=github-pr-review
+        env:
+          REVIEWDOG_GITHUB_API_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/publish-technical-documentation.yml

@@ -0,0 +1,37 @@
+name: "publish-technical-documentation"
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/sources/**"]
+  workflow_dispatch:
+jobs:
+  sync:
+    if: github.repository == 'grafana/k6-docs'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Clone website-sync Action
+        # WEBSITE_SYNC_TOKEN is a fine-grained GitHub Personal Access Token that expires.
+        # It must be regenerated in the grafanabot GitHub account and requires a Grafana organization
+        # GitHub administrator to update the organization secret.
+        # The IT helpdesk can update the organization secret.
+        run: git clone --single-branch --no-tags --depth 1 -b master https://grafanabot:${{ secrets.WEBSITE_SYNC_TOKEN }}@github.com/grafana/website-sync ./.github/actions/website-sync
+
+      - name: Publish to website repository (next)
+        uses: ./.github/actions/website-sync
+        id: publish-next
+        with:
+          repository: grafana/website
+          # To be changed to 'master' once 'jdb/2023-10-k6-docs-migration' is merged.
+          branch: jdb/2023-10-k6-docs-migration
+          host: github.com
+          # PUBLISH_TO_WEBSITE_TOKEN is a fine-grained GitHub Personal Access Token that expires.
+          # It must be regenerated in the grafanabot GitHub account and requires a Grafana organization
+          # GitHub administrator to update the organization secret.
+          # The IT helpdesk can update the organization secret.
+          github_pat: grafanabot:${{ secrets.PUBLISH_TO_WEBSITE_TOKEN }}
+          source_folder: docs/sources
+          target_folder: content/docs/k6

.github/workflows/update-make-docs.yml

@@ -0,0 +1,27 @@
+name: Update `make docs` procedure
+on:
+  schedule:
+    - cron: '0 7 * * 1-5'
+jobs:
+  main:
+    if: github.repository == 'grafana/k6-docs'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Update procedure
+        run: |
+          BRANCH="update-make-docs"
+          git checkout "${BRANCH}"
+          curl -s -Lo docs/docs.mk https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
+          curl -s -Lo docs/make-docs https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
+          if git diff --exit-code; then exit 0; fi
+          git add .
+          git config --local user.email "[email protected]"
+          git config --local user.name "grafanabot"
+          git commit -m "Update \`make docs\` procedure"
+          git push -v origin "refs/heads/${BRANCH}"
+          gh pr create --fill --label type/docs || true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -79,6 +79,3 @@ yarn-error.log
 .vscode/snipsnap.code-snippets
 output 
 .obsidian
-
-# make-docs script fetched from GitHub.
-docs/make-docs

docs/Makefile

@@ -0,0 +1,8 @@
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
+
+include docs.mk

docs/docs.mk

@@ -0,0 +1,112 @@
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
+# A changelog is included in the head of the `make-docs` script.
+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 "  %-15s %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 := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS)))))
+
+# Host port to publish container port to.
+ifeq ($(origin DOCS_HOST_PORT), undefined)
+export DOCS_HOST_PORT := 3002
+endif
+
+# Container image used to perform Hugo build.
+ifeq ($(origin DOCS_IMAGE), undefined)
+export DOCS_IMAGE := grafana/docs-base:latest
+endif
+
+# Container image used for doc-validator linting.
+ifeq ($(origin DOC_VALIDATOR_IMAGE), undefined)
+export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest
+endif
+
+# Container image used for vale linting.
+ifeq ($(origin VALE_IMAGE), undefined)
+export VALE_IMAGE := grafana/vale:latest
+endif
+
+# 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.
+ifeq ($(origin REPOS_PATH), undefined)
+export REPOS_PATH := $(realpath $(GIT_ROOT)/..)
+endif
+
+# How to treat Hugo relref errors.
+ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined)
+export HUGO_REFLINKSERRORLEVEL := WARNING
+endif
+
+.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 -q $(DOCS_IMAGE)
+
+make-docs: ## Fetch the latest make-docs script.
+make-docs:
+	if [[ ! -f "$(CURDIR)/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`.
+docs: docs-pull make-docs
+	$(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: docs-no-pull
+docs-no-pull: ## Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image.
+docs-no-pull: make-docs
+	$(CURDIR)/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 --bind 0.0.0.0 --port 3002 --debug' $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: doc-validator
+doc-validator: ## Run doc-validator on the entire docs folder.
+doc-validator: make-docs
+	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: vale
+vale: ## Run vale on the entire docs folder.
+vale: make-docs
+	DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: update
+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