Ryan Malloy
f4c2a70bbf
Starlight, diataxis-shaped: a tutorial pair, six how-to guides, a generated tool reference plus a configuration reference, and four explanation pages covering architecture, sandbox isolation, see-and-drive, and the failure handling philosophy. The tool reference is generated from the running MCP server's own schemas, so its 33 tools, parameters and defaults cannot drift from the code; the generator asserts its grouping still covers exactly the live tool set. Infrastructure follows the warehacking cookie-cutter (multi-stage Dockerfile, Caddy serving dist with real 404 status, compose profiles for prod and dev, Makefile with a deploy target pointed at docker-2). Two deviations worth noting: remark-gfm is added to the MDX pipeline because Astro enables GFM for .md but not .mdx, so tables silently rendered as run-together paragraphs; and the card icon palette is pinned to the accent because Starlight's staggered grid rotates through colours including purple. Package URLs now point at the Gitea repo and this site.
51 lines
1.9 KiB
Makefile
51 lines
1.9 KiB
Makefile
# mcqemu docs — targets follow the warehacking cookie-cutter.
|
|
|
|
SHELL := /usr/bin/env bash
|
|
.SHELLFLAGS := -eu -o pipefail -c
|
|
.DEFAULT_GOAL := help
|
|
|
|
.PHONY: help
|
|
help: ## Show this help
|
|
@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_-]+:.*##/ {printf " \033[36m%-12s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
|
|
|
|
.PHONY: prod
|
|
prod: ## Build + run the production docs container (Caddy serves dist/)
|
|
docker compose up -d --build docs
|
|
|
|
.PHONY: dev
|
|
dev: ## Run the Astro dev server with HMR (--profile dev)
|
|
docker compose --profile dev up --build docs-dev
|
|
|
|
.PHONY: down
|
|
down: ## Stop and remove the docs containers
|
|
docker compose --profile dev down
|
|
docker compose down
|
|
|
|
.PHONY: logs
|
|
logs: ## Tail logs (works for whichever profile is up)
|
|
docker compose logs -f --tail=100
|
|
|
|
.PHONY: build
|
|
build: ## Build the static site without bringing up Caddy (CI gate)
|
|
docker compose build docs
|
|
|
|
# ---- Production deploy --------------------------------------------------
|
|
#
|
|
# Pulls origin/main on the warehack.ing prod host and rebuilds the docs
|
|
# container. Agent forwarding (-A) lets the remote git pull use the
|
|
# operator's key for Gitea, so nothing persistent is provisioned there.
|
|
#
|
|
# Use docker-2.supportedsystems.net, not warehack.ing: the latter resolves
|
|
# to an IPv4 whose port 22 is unreachable from some networks.
|
|
|
|
DEPLOY_HOST ?= warehack-ing@docker-2.supportedsystems.net
|
|
DEPLOY_PATH ?= ~/mcqemu
|
|
|
|
.PHONY: deploy
|
|
deploy: ## Pull main + rebuild the docs container on the prod host
|
|
@echo "==> deploying $(DEPLOY_HOST):$(DEPLOY_PATH)"
|
|
ssh -A $(DEPLOY_HOST) "cd $(DEPLOY_PATH) && git fetch origin main && git reset --hard origin/main && cd docs-site && make prod"
|
|
@echo "==> verifying by content (these sites return 200 for every path)"
|
|
@curl -sS https://mcqemu.warehack.ing/ | grep -oE "<title>[^<]*</title>" || echo " homepage title not found"
|
|
@curl -sS https://mcqemu.warehack.ing/definitely-not-a-page-xyz/ | grep -oE "<title>[^<]*</title>" || echo " (bogus path returned no title)"
|