Skip to content

Commit d193930

Browse files
jdbaldryjdbaldry
authored
Merge pull request #1386 from grafana/jdb/2023-10-grafana-com
Publish documentation to grafana.com website
2 parents 20031aa + 3179475 commit d193930

File tree

596 files changed

+48959
-21
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

596 files changed

+48959
-21
lines changed

‎.eslintignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
.cache/
22
public/
33
node_modules/
4+
docs/sources/
45
docs/sources/get-started/run-cloud-tests-from-the-CLI.md
56
docs/sources/get-started/run-your-first-tests.md
67
CONTRIBUTING_FILE_FORMAT.md

‎.github/workflows/doc-validator.yml‎

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,28 @@
1-
name: doc-validator
1+
name: Validate documentation
22
on:
33
pull_request:
4-
paths:
5-
- "docs/sources/**"
6-
4+
paths: ["docs/sources/**"]
5+
workflow_dispatch:
76
jobs:
87
doc-validator:
9-
runs-on: ubuntu-latest
10-
container:
11-
image: grafana/doc-validator:v1.9.0
12-
steps:
13-
- name: Checkout repository
14-
uses: actions/checkout@v3
15-
- name: Run doc-validator tool
16-
run: doc-validator --skip-image-validation ./docs/sources /docs/k6
17-
test:
188
runs-on: "ubuntu-latest"
9+
container:
10+
image: "grafana/doc-validator:v4.0.0"
1911
steps:
20-
- name: "Check out code"
21-
uses: "actions/checkout@v1"
22-
- name: "Build Website"
23-
run: |
24-
docker run -v ${PWD}/docs/sources:/hugo/content/docs/k6 --rm grafana/docs-base:latest /bin/bash -c 'make hugo'
12+
- name: "Checkout code"
13+
uses: "actions/checkout@v3"
14+
- name: "Run doc-validator tool"
15+
run: >
16+
doc-validator
17+
'--skip-checks=^image.+$'
18+
docs/sources
19+
/docs/k6
20+
| grep -v "The 'description' parameter in the front matter must be present."
21+
| reviewdog
22+
-f=rdjsonl
23+
--fail-on-error
24+
--filter-mode=nofilter
25+
--name=doc-validator
26+
--reporter=github-pr-review
27+
env:
28+
REVIEWDOG_GITHUB_API_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: "publish-technical-documentation"
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths: ["docs/sources/**"]
7+
workflow_dispatch:
8+
jobs:
9+
sync:
10+
if: github.repository == 'grafana/k6-docs'
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout repository
14+
uses: actions/checkout@v4
15+
16+
- name: Clone website-sync Action
17+
# WEBSITE_SYNC_TOKEN is a fine-grained GitHub Personal Access Token that expires.
18+
# It must be regenerated in the grafanabot GitHub account and requires a Grafana organization
19+
# GitHub administrator to update the organization secret.
20+
# The IT helpdesk can update the organization secret.
21+
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
22+
23+
- name: Publish to website repository (next)
24+
uses: ./.github/actions/website-sync
25+
id: publish-next
26+
with:
27+
repository: grafana/website
28+
# To be changed to 'master' once 'jdb/2023-10-k6-docs-migration' is merged.
29+
branch: jdb/2023-10-k6-docs-migration
30+
host: github.com
31+
# PUBLISH_TO_WEBSITE_TOKEN is a fine-grained GitHub Personal Access Token that expires.
32+
# It must be regenerated in the grafanabot GitHub account and requires a Grafana organization
33+
# GitHub administrator to update the organization secret.
34+
# The IT helpdesk can update the organization secret.
35+
github_pat: grafanabot:${{ secrets.PUBLISH_TO_WEBSITE_TOKEN }}
36+
source_folder: docs/sources
37+
target_folder: content/docs/k6

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Update `make docs` procedure
2+
on:
3+
schedule:
4+
- cron: '0 7 * * 1-5'
5+
jobs:
6+
main:
7+
if: github.repository == 'grafana/k6-docs'
8+
runs-on: ubuntu-latest
9+
steps:
10+
- name: Checkout repository
11+
uses: actions/checkout@v4
12+
13+
- name: Update procedure
14+
run: |
15+
BRANCH="update-make-docs"
16+
git checkout "${BRANCH}"
17+
curl -s -Lo docs/docs.mk https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
18+
curl -s -Lo docs/make-docs https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
19+
if git diff --exit-code; then exit 0; fi
20+
git add .
21+
git config --local user.email "[email protected]"
22+
git config --local user.name "grafanabot"
23+
git commit -m "Update \`make docs\` procedure"
24+
git push -v origin "refs/heads/${BRANCH}"
25+
gh pr create --fill --label type/docs || true
26+
env:
27+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,3 @@ yarn-error.log
7979
.vscode/snipsnap.code-snippets
8080
output
8181
.obsidian
82-
83-
# make-docs script fetched from GitHub.
84-
docs/make-docs

‎docs/Makefile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.ONESHELL:
2+
.DELETE_ON_ERROR:
3+
export SHELL := bash
4+
export SHELLOPTS := pipefail:errexit
5+
MAKEFLAGS += --warn-undefined-variables
6+
MAKEFLAGS += --no-builtin-rule
7+
8+
include docs.mk

‎docs/docs.mk‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
2+
# A changelog is included in the head of the `make-docs` script.
3+
include variables.mk
4+
-include variables.mk.local
5+
6+
.ONESHELL:
7+
.DELETE_ON_ERROR:
8+
export SHELL := bash
9+
export SHELLOPTS := pipefail:errexit
10+
MAKEFLAGS += --warn-undefined-variables
11+
MAKEFLAGS += --no-builtin-rule
12+
13+
.DEFAULT_GOAL: help
14+
15+
# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
16+
.PHONY: help
17+
help: ## Display this help.
18+
help:
19+
@awk 'BEGIN { \
20+
FS = ": ##"; \
21+
printf "Usage:\n make <target>\n\nTargets:\n" \
22+
} \
23+
/^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf " %-15s %s\n", $$1, $$2 }' \
24+
$(MAKEFILE_LIST)
25+
26+
GIT_ROOT := $(shell git rev-parse --show-toplevel)
27+
28+
PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
29+
30+
ifeq ($(PROJECTS),)
31+
$(error "PROJECTS variable must be defined in variables.mk")
32+
endif
33+
34+
# First project is considered the primary one used for doc-validator.
35+
PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS)))))
36+
37+
# Host port to publish container port to.
38+
ifeq ($(origin DOCS_HOST_PORT), undefined)
39+
export DOCS_HOST_PORT := 3002
40+
endif
41+
42+
# Container image used to perform Hugo build.
43+
ifeq ($(origin DOCS_IMAGE), undefined)
44+
export DOCS_IMAGE := grafana/docs-base:latest
45+
endif
46+
47+
# Container image used for doc-validator linting.
48+
ifeq ($(origin DOC_VALIDATOR_IMAGE), undefined)
49+
export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest
50+
endif
51+
52+
# Container image used for vale linting.
53+
ifeq ($(origin VALE_IMAGE), undefined)
54+
export VALE_IMAGE := grafana/vale:latest
55+
endif
56+
57+
# PATH-like list of directories within which to find projects.
58+
# If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
59+
ifeq ($(origin REPOS_PATH), undefined)
60+
export REPOS_PATH := $(realpath $(GIT_ROOT)/..)
61+
endif
62+
63+
# How to treat Hugo relref errors.
64+
ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined)
65+
export HUGO_REFLINKSERRORLEVEL := WARNING
66+
endif
67+
68+
.PHONY: docs-rm
69+
docs-rm: ## Remove the docs container.
70+
$(PODMAN) rm -f $(DOCS_CONTAINER)
71+
72+
.PHONY: docs-pull
73+
docs-pull: ## Pull documentation base image.
74+
$(PODMAN) pull -q $(DOCS_IMAGE)
75+
76+
make-docs: ## Fetch the latest make-docs script.
77+
make-docs:
78+
if [[ ! -f "$(CURDIR)/make-docs" ]]; then
79+
echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2
80+
exit 1
81+
fi
82+
83+
.PHONY: docs
84+
docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. See also `docs-no-pull`.
85+
docs: docs-pull make-docs
86+
$(CURDIR)/make-docs $(PROJECTS)
87+
88+
.PHONY: docs-no-pull
89+
docs-no-pull: ## Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image.
90+
docs-no-pull: make-docs
91+
$(CURDIR)/make-docs $(PROJECTS)
92+
93+
.PHONY: docs-debug
94+
docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
95+
docs-debug: make-docs
96+
WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(CURDIR)/make-docs $(PROJECTS)
97+
98+
.PHONY: doc-validator
99+
doc-validator: ## Run doc-validator on the entire docs folder.
100+
doc-validator: make-docs
101+
DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
102+
103+
.PHONY: vale
104+
vale: ## Run vale on the entire docs folder.
105+
vale: make-docs
106+
DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
107+
108+
.PHONY: update
109+
update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
110+
curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
111+
curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
112+
chmod +x make-docs

0 commit comments

Comments
 (0)