docs/Makefile at main · statusengine/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
# Statusengine documentation site.
#
# Everything runs inside the pinned Hugo *extended* container defined in
# docker-compose.yml. There is deliberately no target that calls a local hugo.

COMPOSE      := docker compose
THEME_TAG    ?= v0.9.7
THEME_REPO   := https://github.com/imfing/hextra.git

# Keep files written by the container owned by the invoking user.
export DOCKER_UID := $(shell id -u)
export DOCKER_GID := $(shell id -g)

.PHONY: help dev build clean shell check shots test-ui test-api upgrade-theme upgrade-scalar

help: ## Show this help
	@grep -hE '^[a-z-]+:.*?## ' $(MAKEFILE_LIST) \
		| awk -F':.*?## ' '{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'

dev: ## Live-reloading server on http://localhost:1313
	$(COMPOSE) up dev

build: ## Production build into public/
	$(COMPOSE) run --rm build

clean: ## Remove generated output
	rm -rf public resources .hugo_build.lock

shell: ## Shell inside the Hugo container
	$(COMPOSE) run --rm shell

check: build ## Build, then verify no external hosts and working highlighting
	@./scripts/check-build.sh

# Docker Desktop under WSL leaves a docker-container buildx builder selected
# that fails to boot ("invalid mount config"); the built-in docker driver
# builds fine. Set per invocation rather than changing the global selection.
shots: build ## Build, then screenshot the site (light and dark) into .shots/
	BUILDX_BUILDER=default $(COMPOSE) build shots
	$(COMPOSE) run --rm shots

test-ui: build ## Build, then drive the browser over behaviour the build cannot see
	BUILDX_BUILDER=default $(COMPOSE) build shots
	$(COMPOSE) run --rm shots node test-lightbox.js
	$(COMPOSE) run --rm shots node test-scrollspy.js
	$(COMPOSE) run --rm shots node test-menu.js
	$(COMPOSE) run --rm shots node test-privacy.js

# The API reference's privacy properties are configuration inside a 3.6 MB
# vendored bundle, so only a running browser can prove them. Everything the
# page requests has to come from our own origin.
test-api: build ## Build, then verify the API reference renders and contacts nobody
	BUILDX_BUILDER=default $(COMPOSE) build shots
	$(COMPOSE) run --rm shots node test-api.js

# Passed through explicitly rather than relying on make's export rules; empty
# falls back to the version pinned in the script.
upgrade-scalar: ## Re-vendor Scalar, e.g. make upgrade-scalar SCALAR_VERSION=1.69.0
	SCALAR_VERSION=$(SCALAR_VERSION) ./scripts/fetch-scalar.sh
	@echo
	@echo "Scalar re-vendored. Run 'make check' and 'make test-api'."

upgrade-theme: ## Re-vendor Hextra, e.g. make upgrade-theme THEME_TAG=v0.9.8
	rm -rf themes/hextra
	git clone --depth 1 --branch $(THEME_TAG) $(THEME_REPO) themes/hextra
	rm -rf themes/hextra/.git themes/hextra/.github themes/hextra/exampleSite \
	       themes/hextra/images themes/hextra/netlify.toml themes/hextra/build.sh \
	       themes/hextra/dev.toml themes/hextra/taskfile.yaml
	# Hextra's own build toolchain. It compiles assets/css/compiled/main.css,
	# which upstream ships already built and which is the only stylesheet this
	# site ever loads — the postCSS path in head-css.html runs solely under
	# --environment=theme. Keeping the manifests would leave a dependency tree
	# we never install in a repository we publish, which is all Dependabot
	# needs to open pull requests against vendored third-party code.
	rm -f themes/hextra/package.json themes/hextra/package-lock.json \
	      themes/hextra/go.mod themes/hextra/postcss.config.js \
	      themes/hextra/tailwind.config.js
	@echo
	@echo "Hextra re-vendored at $(THEME_TAG). Update themes/hextra/UPSTREAM.md, then run 'make check'."