Repository navigation
Expand file tree
/
Copy pathMakefile
More file actions
371 lines (313 loc) · 15.9 KB
/
Copy pathMakefile
File metadata and controls
371 lines (313 loc) · 15.9 KB
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
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
#----------------------------------------------------------------------------------
# Agent Gateway OSS Website - Makefile
#----------------------------------------------------------------------------------
#
# Quick start:
# make help List all targets with short descriptions
# make serve Run the site locally (drafts/future content included)
# make build Build the production site (public/)
#
# Common workflows:
# make fetch-test-artifacts-serve Use latest CI test results and run the site
# make test-run-serve Run doc tests locally, then run the site
# make fetch-test-artifacts-build Use latest CI test results and build for prod
#
# First-time setup:
# make deps Install Python deps (e.g. for doc test scripts)
# make init-git-hooks Use this repo's Git hooks (optional)
#----------------------------------------------------------------------------------
# Repo setup
#----------------------------------------------------------------------------------
# Use this repo's Git hooks (e.g. pre-commit) from .githooks
.PHONY: init-git-hooks
init-git-hooks:
git config core.hooksPath .githooks
# Install Python dependencies (PyYAML) required for doc test scripts
.PHONY: deps
deps:
pip3 install pyyaml
#----------------------------------------------------------------------------------
# Doc tests
#----------------------------------------------------------------------------------
# Doc tests run code blocks from markdown against a cluster. These targets support
# generating scripts, running tests, fetching CI results, and injecting pass/fail
# status into the markdown for the "Verified" badge.
#
# The scripts themselves live in the docs-tests repo, not here -- override
# DOCS_TESTS_DIR if you haven't cloned it as a sibling of this repo. If the
# directory doesn't exist, the targets below clone it, which is how Cloudflare
# Pages gets the scripts: its build checks out only this repo.
#----------------------------------------------------------------------------------
DOCS_TESTS_DIR ?= ../docs-tests
DOCS_TESTS_REPO ?= https://github.com/solo-io/docs-tests.git
# Local CLI smoke tests use main binaries and a mock LLM, without a cluster.
# Override PYTHON to select an environment with PyYAML installed.
PYTHON ?= python3
.PHONY: test-agctl-standalone
test-agctl-standalone:
$(PYTHON) scripts/test-agctl-standalone.py
# Clone docs-tests if it's missing. An existing checkout is left alone.
$(DOCS_TESTS_DIR):
git clone --depth 1 $(DOCS_TESTS_REPO) $(DOCS_TESTS_DIR)
# Test markup lives in docs-tests as annotations, not in these pages. The test
# targets copy this working tree (uncommitted edits included) to
# DOC_TESTS_TREE, attach the annotations to the copy, and run against it, so
# your own pages are never rewritten. The runner writes inside the copy, so
# its out/tests/ is copied back to ./out/tests/ afterwards, even when a test
# fails. Scenarios whose markup did not attach are skipped with a warning;
# out/annotations/attach-report.json lists them.
DOC_TESTS_TREE ?= out/doc-tests-tree
DOC_TESTS_ANNOTATIONS ?= $(DOCS_TESTS_DIR)/products/agentgateway/annotations
# DOC_TESTS_ARGS passes extra runner options, for example to run one page or
# one scenario: DOC_TESTS_ARGS='--file content/docs/<page>.md --test <name>'.
DOC_TESTS_ARGS ?=
DOC_TESTS_RUN = python3 $(DOCS_TESTS_DIR)/scripts/doc_test_run.py --repo-root $(DOC_TESTS_TREE) \
--docs-tests-root $(DOCS_TESTS_DIR) \
--annotation-report $(CURDIR)/out/annotations/attach-report.json $(DOC_TESTS_ARGS)
DOC_TESTS_COPY_BACK = mkdir -p out/tests && rsync -a $(DOC_TESTS_TREE)/out/tests/ out/tests/
# Copy the working tree and attach the test annotations to the copy
.PHONY: test-attach
test-attach: deps | $(DOCS_TESTS_DIR)
rsync -a --delete --exclude .git --exclude node_modules --exclude public \
--exclude resources --exclude out ./ $(DOC_TESTS_TREE)/
python3 $(DOCS_TESTS_DIR)/scripts/annotations.py attach --repo $(DOC_TESTS_TREE) \
--annotations $(DOC_TESTS_ANNOTATIONS) --report $(CURDIR)/out/annotations/attach-report.json
# Generate doc test scripts from markdown (no cluster needed)
.PHONY: test-generate
test-generate: test-attach
$(DOC_TESTS_RUN) --generate-only; status=$$?; $(DOC_TESTS_COPY_BACK); exit $$status
# Run all doc tests (requires kubeconfig / cluster access)
.PHONY: test-run
test-run: test-attach
$(DOC_TESTS_RUN); status=$$?; $(DOC_TESTS_COPY_BACK); exit $$status
# Download latest doc test results from GitHub Actions (main)
.PHONY: test-artifacts-fetch
test-artifacts-fetch: | $(DOCS_TESTS_DIR)
bash $(DOCS_TESTS_DIR)/scripts/doc_test_fetch_artifacts.sh
# Write test pass/fail status into markdown front matter (for Verified badge)
.PHONY: test-status
test-status: deps | $(DOCS_TESTS_DIR)
python3 $(DOCS_TESTS_DIR)/scripts/doc_test_inject_status.py --repo-root .
#----------------------------------------------------------------------------------
# Hugo
#----------------------------------------------------------------------------------
# Build the static site into public/ (production: GC, minify)
# The site's CSS goes through PostCSS + Tailwind from node_modules. Without them
# Hugo fails deep in a template with "Cannot find module 'tailwindcss/nesting'",
# which does not say what to do. A fresh clone or git worktree has no
# node_modules, so check first and say so plainly.
.PHONY: check-node-deps
check-node-deps:
@test -d node_modules/tailwindcss || { echo "node_modules is missing. Run 'npm install' in $(CURDIR) first."; exit 1; }
# On a Cloudflare Pages preview (CF_PAGES is set and the branch isn't main), skip
# the version trees that aren't in hugo.yaml's `params.versions`, unless the
# branch changed one of them. Production (main) and plain local builds still
# build everything. PREVIEW=1 tries the preview build locally.
PREVIEW ?= $(if $(CF_PAGES),$(filter-out main,$(CF_PAGES_BRANCH)))
# pr-tracker-* branches come in batches and fill the Cloudflare build queue, so
# their previews build only the version trees the branch changed (plus the first
# listed version when it also changes shared files), without the search index. Try it locally with PREVIEW=1 CF_PAGES_BRANCH=pr-tracker-x.
PR_TRACKER_PREVIEW ?= $(if $(PREVIEW),$(filter pr-tracker-%,$(CF_PAGES_BRANCH)))
.PHONY: build
build: check-node-deps
$(if $(PREVIEW),pip3 install -q pyyaml || true)
$(if $(PREVIEW),python3 scripts/local-version-config.py --preview-base origin/main $(if $(PR_TRACKER_PREVIEW),--only-changed))
$(if $(PR_TRACKER_PREVIEW),HUGO_PARAMS_SEARCH_ENABLE=false )hugo --gc --minify $(if $(PREVIEW),--config hugo.yaml$(COMMA)hugo-local-versions.yaml)
# The local servers build only the versions listed in hugo.yaml's
# `params.versions`. content/docs/ also holds every older version tree, which
# production still publishes. scripts/local-version-config.py derives the skip list from hugo.yaml and
# writes hugo-local-versions.yaml (gitignored). FULL=1 builds everything.
# VERSION=<linkVersion> builds only that listed version (VERSION=latest for the
# `latest` entry), for a faster preview.
COMMA := ,
LOCAL_VERSIONS_CONFIG = $(if $(FULL),,--config hugo.yaml,hugo-local-versions.yaml)
# NO_SEARCH=1 builds without the search index (the search box does nothing),
# for a faster preview.
NO_SEARCH_ENV = $(if $(NO_SEARCH),HUGO_PARAMS_SEARCH_ENABLE=false )
.PHONY: local-version-config
local-version-config:
@$(if $(FULL),:,python3 scripts/local-version-config.py $(if $(VERSION),--version $(VERSION)))
# Start local dev server (drafts and future-dated content shown)
.PHONY: serve
serve: check-node-deps local-version-config
$(NO_SEARCH_ENV)hugo server --buildDrafts --buildFuture $(LOCAL_VERSIONS_CONFIG)
# Start local server with production-like build (GC, minify, no drafts)
.PHONY: serve-prod
serve-prod: check-node-deps local-version-config
$(NO_SEARCH_ENV)hugo server --gc --minify $(LOCAL_VERSIONS_CONFIG)
# Alias for serve (drafts and future-dated content shown)
.PHONY: server
server: serve
# Alias for serve-prod (production-like build, no drafts)
.PHONY: server-prod
server-prod: serve-prod
# Remove public/ and resources/ (Hugo output and cache)
.PHONY: clean
clean:
rm -rf public resources
#----------------------------------------------------------------------------------
# Framework tests
#----------------------------------------------------------------------------------
# Playwright HTML harness from github.com/solo-io/docs-theme-extras. The harness
# does NOT build the site; these targets build first, then point Playwright at
# public/ via .docs-test.toml. Distinct from the doc tests above: those run
# code blocks against a cluster; these check rendered HTML quality.
#
# Targets are prefixed `framework-test-*` so they don't collide with the
# doc-test `test-*` namespace above.
#----------------------------------------------------------------------------------
# Path to a docs-theme-extras checkout that hosts the harness. CI sets this
# inside $GITHUB_WORKSPACE; locally it defaults to a sibling clone.
# Override with: make framework-test FRAMEWORK_EXTRAS_DIR=/abs/path
FRAMEWORK_EXTRAS_DIR ?= ../docs-theme-extras
# One-time install: npm packages and Playwright browser binaries (chromium,
# firefox, webkit) inside the docs-theme-extras checkout. ~120-180 MB of
# downloads, ~1-3 minutes.
# Serving the HTML report binds a port and BLOCKS until interrupted, so it must
# never run unattended: in CI it hangs the job, and in any scripted/non-tty run
# it hangs the caller. Gate it on an interactive terminal AND the absence of CI.
# The report is still written to playwright-report/ either way — view it with
# `make framework-test-report`.
SHOW_REPORT = if [ -t 1 ] && [ -z "$$CI" ]; then npx playwright show-report; fi
.PHONY: framework-test-install
framework-test-install:
@if [ ! -d "$(FRAMEWORK_EXTRAS_DIR)" ]; then \
echo "docs-theme-extras checkout not found at $(FRAMEWORK_EXTRAS_DIR)." >&2; \
echo "Clone it as a sibling, or set FRAMEWORK_EXTRAS_DIR=/path/to/docs-theme-extras." >&2; \
exit 1; \
fi
cd $(FRAMEWORK_EXTRAS_DIR) && npm install
cd $(FRAMEWORK_EXTRAS_DIR) && npx playwright install --with-deps chromium firefox webkit
# Build the site and run the full framework suite (static + browser +
# cross-browser). Always opens the HTML report after the run.
.PHONY: framework-test
framework-test:
@$(MAKE) _framework_test_preflight
rm -rf public
hugo --gc --minify > .build.log 2>&1
cd $(FRAMEWORK_EXTRAS_DIR) && \
(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test; \
result=$$?; $(SHOW_REPORT); exit $$result)
# Build the site and run only the static specs. Fastest iteration loop --
# no browser launch.
.PHONY: framework-test-static
framework-test-static:
@$(MAKE) _framework_test_preflight
rm -rf public
hugo --gc --minify > .build.log 2>&1
cd $(FRAMEWORK_EXTRAS_DIR) && \
(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test --project=static; \
result=$$?; $(SHOW_REPORT); exit $$result)
# Build the site and run only the content specs (markdown-leaks,
# built-html-integrity, copy-md-fidelity, hugo-warnings, dev-build, plus the
# source scanners curl-quotes/tab-syntax/shortcode-args/include-form/
# cascade-type). This is the project a content-only PR needs; mirrors CI.
.PHONY: framework-test-content
framework-test-content:
@$(MAKE) _framework_test_preflight
rm -rf public
hugo --gc --minify > .build.log 2>&1
cd $(FRAMEWORK_EXTRAS_DIR) && \
(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test --project=content; \
result=$$?; npx playwright show-report; exit $$result)
# Build the site and run chromium browser specs (theme toggle, mermaid,
# contrast, viewport, sidebar rail, toc, alerts, back-to-top, brand). The
# all-page console-error crawl is a separate "browser-crawl" project; the
# full `framework-test` target runs it.
.PHONY: framework-test-browser
framework-test-browser:
@$(MAKE) _framework_test_preflight
rm -rf public
hugo --gc --minify > .build.log 2>&1
cd $(FRAMEWORK_EXTRAS_DIR) && \
(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test --project=browser; \
result=$$?; $(SHOW_REPORT); exit $$result)
# Build the site and run cross-browser desktop specs across chromium,
# firefox, and webkit.
.PHONY: framework-test-cross-browser
framework-test-cross-browser:
@$(MAKE) _framework_test_preflight
rm -rf public
hugo --gc --minify > .build.log 2>&1
cd $(FRAMEWORK_EXTRAS_DIR) && \
(DOCS_TEST_CONFIG=$(abspath ./.docs-test.toml) npx playwright test \
--project=cross-browser-chromium \
--project=cross-browser-firefox \
--project=cross-browser-webkit; \
result=$$?; $(SHOW_REPORT); exit $$result)
# Open the most recent Playwright HTML report. Handy when an earlier
# framework-test target was interrupted before reaching the report step.
.PHONY: framework-test-report
framework-test-report:
@if [ ! -d "$(FRAMEWORK_EXTRAS_DIR)" ]; then \
echo "docs-theme-extras checkout not found at $(FRAMEWORK_EXTRAS_DIR)." >&2; \
exit 1; \
fi
cd $(FRAMEWORK_EXTRAS_DIR) && npx playwright show-report
# Shared preflight for the framework-test-* targets.
.PHONY: _framework_test_preflight
_framework_test_preflight:
@if [ ! -d "$(FRAMEWORK_EXTRAS_DIR)" ]; then \
echo "docs-theme-extras checkout not found at $(FRAMEWORK_EXTRAS_DIR)." >&2; \
echo "Clone it as a sibling, or set FRAMEWORK_EXTRAS_DIR=/path/to/docs-theme-extras." >&2; \
exit 1; \
fi
@if [ ! -d "$(FRAMEWORK_EXTRAS_DIR)/node_modules" ]; then \
echo "Run 'make framework-test-install' first." >&2; exit 1; \
fi
#----------------------------------------------------------------------------------
# Playwright screenshots for docs images
#----------------------------------------------------------------------------------
# These targets live in the repo, not in docs-theme-extras. They generate the
# committed UI screenshots under assets/img/ using the local Playwright setup in
# ./playwright.
#----------------------------------------------------------------------------------
PLAYWRIGHT_DIR ?= playwright
.PHONY: playwright-install
playwright-install:
@if [ ! -d "$(PLAYWRIGHT_DIR)" ]; then \
echo "Playwright directory not found at $(PLAYWRIGHT_DIR)." >&2; \
exit 1; \
fi
cd $(PLAYWRIGHT_DIR) && npm ci
cd $(PLAYWRIGHT_DIR) && npx playwright install --with-deps chromium
.PHONY: playwright-test
playwright-test:
@if [ ! -d "$(PLAYWRIGHT_DIR)" ]; then \
echo "Playwright directory not found at $(PLAYWRIGHT_DIR)." >&2; \
exit 1; \
fi
cd $(PLAYWRIGHT_DIR) && npm run test:standalone
.PHONY: playwright-update-images
playwright-update-images: playwright-install
@if [ ! -d "$(PLAYWRIGHT_DIR)" ]; then \
echo "Playwright directory not found at $(PLAYWRIGHT_DIR)." >&2; \
exit 1; \
fi
cd $(PLAYWRIGHT_DIR) && npm run update
cd $(PLAYWRIGHT_DIR) && npm run sync-docs
#----------------------------------------------------------------------------------
# Combined workflows
#----------------------------------------------------------------------------------
# One-step targets that chain: test data → inject status → build or serve.
#----------------------------------------------------------------------------------
# Fetch CI test results, inject status, build site for production
.PHONY: fetch-test-artifacts-build
fetch-test-artifacts-build: test-artifacts-fetch test-status build
# Run doc tests, inject status, build site
.PHONY: test-run-build
test-run-build: test-run test-status build
# Fetch CI test results, inject status, serve site locally
.PHONY: fetch-test-artifacts-serve
fetch-test-artifacts-serve: test-artifacts-fetch test-status serve
# Run doc tests locally, inject status, serve site locally
.PHONY: test-run-serve
test-run-serve: test-run test-status serve
#----------------------------------------------------------------------------------
# Help
#----------------------------------------------------------------------------------
# Show all targets and their descriptions
.PHONY: help
help:
@awk '/^# .*$$/ { desc=substr($$0,3); next } /^\.PHONY: / { gsub(/^\.PHONY: /,""); printf "\033[36m%-20s\033[0m %s\n", $$1, desc }' $(MAKEFILE_LIST) | sort -u
.DEFAULT_GOAL := help