IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update make-docs script (#66841)

Browse Source 
Update centralized make-docs procedure

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
Jack Baldry
2023-04-24 16:23:33 +01:00
committed by GitHub
parent 872e79f687
commit 3c655821e8
3 changed files with 395 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/docs.mk
View File

@@ -14,7 +14,12 @@ MAKEFLAGS += --no-builtin-rule
.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)
@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)
@@ -25,26 +30,38 @@ $(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)))
PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS)))))
# Name for the container.
ifeq ($(origin DOCS_CONTAINER), undefined)
export DOCS_CONTAINER := $(PRIMARY_PROJECT)-docs
endif
# 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
# 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.
@@ -56,27 +73,38 @@ docs-pull: ## Pull documentation base 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
if [[ ! -f "$(PWD)/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.
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
$(PWD)/make-docs $(PROJECTS)
.PHONY: docs-no-pull
docs-no-pull: ## Serve documentation locally without pulling the latest docs-base image.
docs-no-pull: ## Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image.
docs-no-pull: make-docs
$(PWD)/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 --debug' $(PWD)/make-docs $(PROJECTS)
.PHONY: doc-validator
doc-validator: ## Run docs-validator on the entire docs folder.
doc-validator: make-docs
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/%:
doc-validator/%: make-docs
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.
.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