Skip to content

chore: standardize the docs Makefile workflow #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cmilesio merged 1 commit into from
Aug 7, 2026
Merged

chore: standardize the docs Makefile workflow #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 13 additions & 41 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,37 +30,9 @@ ifeq ($(APP_ENV),production)
COMPOSE_COMMAND=docker-compose -f docker-compose.yml -f docker-compose.prod.yml
endif

#----------------------
# Terminal
#----------------------
HELP_NAME := docs

GREEN := $(shell tput -Txterm setaf 2)
WHITE := $(shell tput -Txterm setaf 7)
YELLOW := $(shell tput -Txterm setaf 3)
RESET := $(shell tput -Txterm sgr0)

#------------------------------------------------------------------
# - Add the following 'help' target to your Makefile
# - Add help text after each target name starting with '\#\#'
# - A category can be added with @category
#------------------------------------------------------------------

.PHONY: build test

HELP_FUN = \
%help; \
while(<>) { \
push @{$$help{$$2 // 'options'}}, [$$1, $$3] if /^([a-zA-Z\-]+)\s*:.*\#\#(?:@([a-zA-Z\-]+))?\s(.*)$$/ }; \
print "\n"; \
for (sort keys %help) { \
print "${WHITE}$$_${RESET \
}\n"; \
for (@{$$help{$$_}}) { \
$$sep = " " x (32 - length $$_->[0]); \
print " ${YELLOW}$$_->[0]${RESET}$$sep${GREEN}$$_->[1]${RESET}\n"; \
}; \
print ""; \
}
HELP_FUN = %help; while (<>) { /^([A-Za-z0-9_-]+)\s*:.*\#\#(?:@([A-Za-z0-9_-]+))?\s(.*)$$/ or next; push @{$$help{$$2 || "other"}}, [$$1, $$3]; $$width = length($$1) if length($$1) > $$width } print "\e[1;97m$(or $(HELP_NAME),$(notdir $(CURDIR)))\e[0m\n\n"; for $$category (sort keys %help) { print "\e[1;97m$$category\e[0m\n"; for $$entry (@{$$help{$$category}}) { printf " \e[1;32m%-*s\e[0m \e[90m%s\e[0m\n", $$width, $$entry->[0], $$entry->[1] } }

help: ##@other Show this help.
@perl -e '$(HELP_FUN)' $(MAKEFILE_LIST)
Expand All @@ -69,27 +41,27 @@ help: ##@other Show this help.
# docs
#----------------------

docs-generate: ##@docs Generate docs pages and example manifest
docs-generate: ##@documentation Generate docs pages and example manifest
@cd backend && go run . docs:generate

docs-proof-stats: ##@docs Refresh checked-in proof statistics from sibling repositories
docs-proof-refresh: ##@documentation Refresh checked-in proof statistics from sibling repositories
@cd docs && npm run proof:refresh

docs-check-proof-stats: ##@docs Verify checked-in proof statistics match sibling repositories
docs-proof-check: ##@documentation Verify checked-in proof statistics match sibling repositories
@cd docs && npm run proof:check

docs-check-scenarios: ##@docs Verify generated scenario pages match framework specs
docs-scenarios-check: ##@documentation Verify generated scenario pages match framework specs
@cd ../goforj && go run ./cmd/forj scenario:generate --all --check

docs-build: docs-check-proof-stats docs-check-scenarios ##@docs Verify generated evidence and build VitePress docs
docs-build: docs-proof-check docs-scenarios-check ##@documentation Verify generated evidence and build VitePress docs
@cd docs && npm run build

docs-embed: ##@docs Copy built docs into backend embed folder
docs-embed: ##@documentation Copy built docs into backend embed folder
@rm -rf backend/frontend/dist
@mkdir -p backend/frontend/dist
@cp -R docs/.vitepress/dist/. backend/frontend/dist/

docs-package: ##@docs Generate + build docs and stage for backend
docs-package: ##@documentation Generate + build docs and stage for backend
@$(MAKE) docs-generate
@$(MAKE) docs-build
@$(MAKE) docs-embed
Expand All @@ -101,21 +73,21 @@ docs-package: ##@docs Generate + build docs and stage for backend
DOCKER_PROD_IMAGE ?= docs-web:latest
DOCKER_PROD_PUSH ?= 0

docker-production: ##@docker Build the production web image
docker-build-prod: ##@docker Build the production web image
@docker buildx build \
-f containers/web/Dockerfile \
--build-arg GA_MEASUREMENT_ID=$(GA_MEASUREMENT_ID) \
-t $(DOCKER_PROD_IMAGE) \
$(if $(filter 1 true yes,$(DOCKER_PROD_PUSH)),--push,--load) \
.

docker-build-prod: docker-generate-docs-prod docker-production ##@docker Generate docs and build production image
docker-package-prod: docker-generate-prod docker-build-prod ##@docker Generate docs and build the production image

docker-generate-docs-prod: ##@docker Generate docs from upstream repos in a one-off container (updates docs/libraries/*.md)
docker-generate-prod: ##@docker Generate docs from upstream repositories in a one-off container
@$(COMPOSE_COMMAND) run --rm --build docs-generate

docker-deploy-prod: ##@docker Generate docs, build prod image, and roll web container
@$(MAKE) docker-build-prod
@$(MAKE) docker-package-prod
@$(COMPOSE_COMMAND) up -d --force-recreate web

#----------------------
Expand Down