github.com/grafana/pyroscope@v1.18.0/docs/docs.mk (about)

     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  # Host port to publish container port to.
    35  ifeq ($(origin DOCS_HOST_PORT), undefined)
    36  export DOCS_HOST_PORT := 3002
    37  endif
    38  
    39  # Container image used to perform Hugo build.
    40  ifeq ($(origin DOCS_IMAGE), undefined)
    41  export DOCS_IMAGE := grafana/docs-base:latest
    42  endif
    43  
    44  # Container image used for Vale linting.
    45  ifeq ($(origin VALE_IMAGE), undefined)
    46  export VALE_IMAGE := grafana/vale:latest
    47  endif
    48  
    49  # PATH-like list of directories within which to find projects.
    50  # If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
    51  ifeq ($(origin REPOS_PATH), undefined)
    52  export REPOS_PATH := $(realpath $(GIT_ROOT)/..)
    53  endif
    54  
    55  # How to treat Hugo relref errors.
    56  ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined)
    57  export HUGO_REFLINKSERRORLEVEL := WARNING
    58  endif
    59  
    60  # Whether to pull the latest container image before running the container.
    61  ifeq ($(origin PULL), undefined)
    62  export PULL := true
    63  endif
    64  
    65  .PHONY: docs-rm
    66  docs-rm: ## Remove the docs container.
    67  	$(PODMAN) rm -f $(DOCS_CONTAINER)
    68  
    69  .PHONY: docs-pull
    70  docs-pull: ## Pull documentation base image.
    71  	$(PODMAN) pull -q $(DOCS_IMAGE)
    72  
    73  make-docs: ## Fetch the latest make-docs script.
    74  make-docs:
    75  	if [[ ! -f "$(CURDIR)/make-docs" ]]; then
    76  		echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2
    77  		exit 1
    78  	fi
    79  
    80  .PHONY: docs
    81  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`.
    82  ifeq ($(PULL), true)
    83  docs: docs-pull make-docs
    84  else
    85  docs: make-docs
    86  endif
    87  	$(CURDIR)/make-docs $(PROJECTS)
    88  
    89  .PHONY: docs-debug
    90  docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
    91  docs-debug: make-docs
    92  	WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --logLevel debug' $(CURDIR)/make-docs $(PROJECTS)
    93  
    94  .PHONY: vale
    95  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`.
    96  vale: make-docs
    97  ifeq ($(PULL), true)
    98  	$(PODMAN) pull -q $(VALE_IMAGE)
    99  endif
   100  	DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
   101  
   102  .PHONY: update
   103  update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
   104  	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
   105  	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
   106  	chmod +x make-docs
   107  
   108  # ls static/templates/ | sed 's/-template\.md//' | xargs
   109  TOPIC_TYPES := concept multiple-tasks reference section task tutorial visualization
   110  .PHONY: $(patsubst %,topic/%,$(TOPIC_TYPES))
   111  topic/%: ## Create a topic from the Writers' Toolkit template. Specify the topic type as the target, for example, `make topic/task TOPIC_PATH=sources/my-new-topic.md`.
   112  $(patsubst %,topic/%,$(TOPIC_TYPES)):
   113  	$(if $(TOPIC_PATH),,$(error "You must set the TOPIC_PATH variable to the path where the $(@F) topic will be created. For example: make $(@) TOPIC_PATH=sources/my-new-topic.md"))
   114  	mkdir -p $(dir $(TOPIC_PATH))
   115  	curl -s -o $(TOPIC_PATH) https://raw.githubusercontent.com/grafana/writers-toolkit/refs/heads/main/docs/static/templates/$(@F)-template.md