-
Notifications
You must be signed in to change notification settings - Fork 223
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1386 from grafana/jdb/2023-10-grafana-com
Publish documentation to grafana.com website
- Loading branch information
Showing
596 changed files
with
48,959 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 }}" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.