1735db4c3b
# What this PR does The `docs/reference` shortcode supports contextual destinations and version inference. `<ONCALL VERSION>` is inferred to match the version of the documentation set. For example, the inferred version for the page /docs/grafana/oncall/latest/get-started/ is "latest". It can also be overriden using front matter. Given the same page, but with the additional front matter `oncall_version: next`, the variable is substituted with "next" rather than "latest". Contextual destinations are achieved using repeated labels in the shortcode inner text. The format is [<LABEL>]: "<PAGE PATH PREFIX> -> <HUGO REFERENCE>". - _`<LABEL>`_ matches the reference style link label used in the rest of the text. - _`<PAGE PATH PREFIX>`_ is matched against the page during the production build. If the match is successful, the destination that is used is _`<HUGO REFERENCE>`_. The first matching prefix is used, not the longest matching prefix. ## Which issue(s) this PR fixes - Broken links due to ambiguous relref resolution. Any relref parameter that does not start with either `/`, `./`, or `../` can resolve ambiguously and is resulting in broken link behavior on the current site. - Broken links in Grafana Cloud. We mount OnCall documentation in Grafana Cloud. In https://github.com/grafana/website/pull/13872 the location will become /docs/grafana-cloud/alerting-and-irm/oncall. This PR is intended to be merged alongside that PR. --------- Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Joey Orlando <joey.orlando@grafana.com>
117 lines
3.8 KiB
Makefile
117 lines
3.8 KiB
Makefile
# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
|
|
# 4.0.0 (2023-06-06)
|
|
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)))))
|
|
|
|
# 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
|
|
|
|
# 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 $(DOCS_IMAGE)
|
|
|
|
make-docs: ## Fetch the latest make-docs script.
|
|
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, 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 `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 --bind 0.0.0.0 --port 3002 --debug' $(PWD)/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) $(PWD)/make-docs $(PROJECTS)
|
|
|
|
.PHONY: vale
|
|
vale: ## Run vale on the entire docs folder.
|
|
vale: make-docs
|
|
DOCS_IMAGE=$(VALE_IMAGE) $(PWD)/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
|