Skip to content

Commit eba827c

Browse files
enghub-ops-integration[bot]usmangt
enghub-ops-integration[bot]
and
usmangt
authored
Add the make docs procedure (#257)
Co-authored-by: enghub-ops-integration[bot] <141459326+enghub-ops-integration[bot]@users.noreply.github.com> Co-authored-by: Usman Ahmad <usman.ahmad@grafana.com>
1 parent abde364 commit eba827c

File tree

5 files changed

+1060
-0
lines changed

5 files changed

+1060
-0
lines changed

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
name: Update `make docs` procedure
2+
on:
3+
schedule:
4+
- cron: '0 7 * * 1-5'
5+
workflow_dispatch:
6+
jobs:
7+
main:
8+
if: github.repository == 'grafana/google-sheets-datasource'
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
12+
- uses: grafana/writers-toolkit/update-make-docs@update-make-docs/v1

‎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: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
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+
# Whether to pull the latest container image before running the container.
69+
ifeq ($(origin PULL), undefined)
70+
export PULL := true
71+
endif
72+
73+
.PHONY: docs-rm
74+
docs-rm: ## Remove the docs container.
75+
$(PODMAN) rm -f $(DOCS_CONTAINER)
76+
77+
.PHONY: docs-pull
78+
docs-pull: ## Pull documentation base image.
79+
$(PODMAN) pull -q $(DOCS_IMAGE)
80+
81+
make-docs: ## Fetch the latest make-docs script.
82+
make-docs:
83+
if [[ ! -f "$(CURDIR)/make-docs" ]]; then
84+
echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2
85+
exit 1
86+
fi
87+
88+
.PHONY: docs
89+
docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. To not pull the image, set `PULL=false`.
90+
ifeq ($(PULL), true)
91+
docs: docs-pull make-docs
92+
else
93+
docs: make-docs
94+
endif
95+
$(CURDIR)/make-docs $(PROJECTS)
96+
97+
.PHONY: docs-debug
98+
docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
99+
docs-debug: make-docs
100+
WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(CURDIR)/make-docs $(PROJECTS)
101+
102+
.PHONY: doc-validator
103+
doc-validator: ## Run doc-validator on the entire docs folder which includes pulling the latest `DOC_VALIDATOR_IMAGE` (default: `grafana/doc-validator:latest`) container image. To not pull the image, set `PULL=false`.
104+
doc-validator: make-docs
105+
ifeq ($(PULL), true)
106+
$(PODMAN) pull -q $(DOC_VALIDATOR_IMAGE)
107+
endif
108+
DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
109+
110+
.PHONY: vale
111+
vale: ## Run vale on the entire docs folder which includes pulling the latest `VALE_IMAGE` (default: `grafana/vale:latest`) container image. To not pull the image, set `PULL=false`.
112+
vale: make-docs
113+
ifeq ($(PULL), true)
114+
$(PODMAN) pull -q $(VALE_IMAGE)
115+
endif
116+
DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
117+
118+
.PHONY: update
119+
update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
120+
curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
121+
curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
122+
chmod +x make-docs

0 commit comments

Comments
 (0)