mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Use centralized make-docs script from Writers' Toolkit (#66440)
- 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>
This commit is contained in:
Jack Baldry
GitHub
parent
04370f92dc
commit
43fbb9804e
1
.gitignore
vendored
1
.gitignore
vendored
@ -191,3 +191,4 @@ public/api-spec.json
|
||||
deployment_tools_config.json
|
||||
|
||||
.betterer.cache
|
||||
/docs/make-docs
|
||||
|
||||
@ -1,33 +1,8 @@
|
||||
.PHONY: pull docs docs-quick docs-no-pull docs-test docs-local-static
|
||||
.ONESHELL:
|
||||
.DELETE_ON_ERROR:
|
||||
export SHELL := bash
|
||||
export SHELLOPTS := pipefail:errexit
|
||||
MAKEFLAGS += --warn-undefined-variables
|
||||
MAKEFLAGS += --no-builtin-rule
|
||||
|
||||
PODMAN = $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
|
||||
IMAGE = grafana/docs-base:latest
|
||||
CONTENT_PATH = /hugo/content/docs/grafana/latest
|
||||
LOCAL_STATIC_PATH = ../../website/static
|
||||
PORT = 3002:3002
|
||||
|
||||
pull:
|
||||
$(PODMAN) pull $(IMAGE)
|
||||
|
||||
docs: pull
|
||||
$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) make server
|
||||
|
||||
docs-preview: pull
|
||||
$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) make server BUILD_DRAFTS=true
|
||||
|
||||
docs-no-pull:
|
||||
$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) make server
|
||||
|
||||
docs-test: pull
|
||||
$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z --rm -it $(IMAGE) make prod
|
||||
|
||||
# expects that you have grafana/website checked out in same path as the grafana repo.
|
||||
docs-local-static: pull
|
||||
if [ ! -d "$(LOCAL_STATIC_PATH)" ]; then echo "local path (website project) $(LOCAL_STATIC_PATH) not found"]; exit 1; fi
|
||||
$(PODMAN) run --init -v $(shell pwd)/sources:$(CONTENT_PATH):Z \
|
||||
-v $(shell pwd)/$(LOCAL_STATIC_PATH):/hugo/static:Z -p $(PORT) --rm -it $(IMAGE)
|
||||
|
||||
.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/%:
|
||||
$(PODMAN) run --init -v "$(shell pwd)/sources:/sources" grafana/doc-validator:latest --skip-image-validation --include=$(subst doc-validator/,,$@) ./sources /docs/grafana/latest
|
||||
include docs.mk
|
||||
|
||||
82
docs/docs.mk
Normal file
82
docs/docs.mk
Normal file
@ -0,0 +1,82 @@
|
||||
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: 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
|
||||
2
docs/variables.mk
Normal file
2
docs/variables.mk
Normal file
@ -0,0 +1,2 @@
|
||||
# List of projects to provide to the make-docs script.
|
||||
PROJECTS = grafana
|
||||
Loading…
Reference in New Issue
Block a user