From 890c500240cb1c596fd67cd665a195e425186845 Mon Sep 17 00:00:00 2001 From: Chris Miles Date: Sat, 1 Aug 2026 03:06:16 +0000 Subject: [PATCH 1/5] docs: improve development workflow --- Makefile | 30 ++++++++++++++++++++++++++++++ README.md | 10 +--------- 2 files changed, 31 insertions(+), 9 deletions(-) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..37339e8 --- /dev/null +++ b/Makefile @@ -0,0 +1,30 @@ +GREEN := $(shell tput -Txterm setaf 2) +WHITE := $(shell tput -Txterm setaf 7) +YELLOW := $(shell tput -Txterm setaf 3) +RESET := $(shell tput -Txterm sgr0) + +.PHONY: help + +HELP_FUN = %help; while(<>) { if (/^([A-Za-z0-9_-]+)\s*:.*\#\#(?:@([A-Za-z0-9_-]+))?\s(.*)$$/) { push @{$$help{$$2 || "other"}}, [$$1, $$3]; $$width = length($$1) if length($$1) > $$width } } print "\n"; for $$category (sort keys %help) { print "${WHITE}$$category${RESET}\n"; for $$entry (@{$$help{$$category}}) { printf " ${YELLOW}%-*s${RESET} ${GREEN}%s${RESET}\n", $$width, $$entry->[0], $$entry->[1] } } + +help: ##@other Show this help. + @perl -e '$(HELP_FUN)' $(MAKEFILE_LIST) + +##@quality +test: ##@quality Run the test suites. + go test ./... + go -C docs test ./... + go -C examples test ./... + +test-race: ##@quality Run the race-enabled test suite. + go test -race ./... + +vet: ##@quality Run Go vet for every module. + go vet ./... + go -C docs vet ./... + go -C examples vet ./... + +##@documentation +generate: ##@documentation Regenerate documentation examples and README content. + go -C docs run ./examplegen + go -C docs run ./readme diff --git a/README.md b/README.md index 9a782ed..82c0ba4 100644 --- a/README.md +++ b/README.md @@ -1160,14 +1160,6 @@ fmt.Println(out == dir) `docs` and `examples` are separate Go modules, keeping their tooling and generated programs out of the library module download. -Run the tests and rebuild the generated examples and README with: - -```sh -go test ./... -go -C docs test ./... -go -C examples test ./... -go -C docs run ./examplegen -go -C docs run ./readme -``` +Use `make test`, `make test-race`, `make vet`, and `make generate`. The test and vet targets cover all three modules; generation rebuilds the examples and README. Licensed under the [MIT License](./LICENSE). From c7cfcc0a7a754dd41009168845fb9883587e0973 Mon Sep 17 00:00:00 2001 From: Chris Miles Date: Sat, 1 Aug 2026 03:16:00 +0000 Subject: [PATCH 2/5] chore: compact Makefile help boilerplate --- Makefile | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 37339e8..d442369 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,6 @@ -GREEN := $(shell tput -Txterm setaf 2) -WHITE := $(shell tput -Txterm setaf 7) -YELLOW := $(shell tput -Txterm setaf 3) -RESET := $(shell tput -Txterm sgr0) - .PHONY: help -HELP_FUN = %help; while(<>) { if (/^([A-Za-z0-9_-]+)\s*:.*\#\#(?:@([A-Za-z0-9_-]+))?\s(.*)$$/) { push @{$$help{$$2 || "other"}}, [$$1, $$3]; $$width = length($$1) if length($$1) > $$width } } print "\n"; for $$category (sort keys %help) { print "${WHITE}$$category${RESET}\n"; for $$entry (@{$$help{$$category}}) { printf " ${YELLOW}%-*s${RESET} ${GREEN}%s${RESET}\n", $$width, $$entry->[0], $$entry->[1] } } +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 "\n"; for $$category (sort keys %help) { print "\e[37m$$category\e[0m\n"; for $$entry (@{$$help{$$category}}) { printf " \e[33m%-*s\e[0m \e[32m%s\e[0m\n", $$width, $$entry->[0], $$entry->[1] } } help: ##@other Show this help. @perl -e '$(HELP_FUN)' $(MAKEFILE_LIST) From 7285d59898ab953497ddde39c9a1c2e5680552a9 Mon Sep 17 00:00:00 2001 From: Chris Miles Date: Sat, 1 Aug 2026 03:25:39 +0000 Subject: [PATCH 3/5] chore: align Makefile help styling --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index d442369..703c206 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ .PHONY: help -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 "\n"; for $$category (sort keys %help) { print "\e[37m$$category\e[0m\n"; for $$entry (@{$$help{$$category}}) { printf " \e[33m%-*s\e[0m \e[32m%s\e[0m\n", $$width, $$entry->[0], $$entry->[1] } } +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) From 5b9a44dfded05c12b066526d01a55071a993506f Mon Sep 17 00:00:00 2001 From: Chris Miles Date: Sat, 1 Aug 2026 04:18:15 +0000 Subject: [PATCH 4/5] chore: standardize Makefile task names --- Makefile | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 703c206..3336e18 100644 --- a/Makefile +++ b/Makefile @@ -5,16 +5,17 @@ HELP_FUN = %help; while (<>) { /^([A-Za-z0-9_-]+)\s*:.*\#\#(?:@([A-Za-z0-9_-]+)) help: ##@other Show this help. @perl -e '$(HELP_FUN)' $(MAKEFILE_LIST) -##@quality -test: ##@quality Run the test suites. +##@tests +test: ##@tests Run the test suites. go test ./... go -C docs test ./... go -C examples test ./... -test-race: ##@quality Run the race-enabled test suite. +test-race: ##@tests Run the race-enabled test suite. go test -race ./... -vet: ##@quality Run Go vet for every module. +##@analysis +vet: ##@analysis Run Go vet for every module. go vet ./... go -C docs vet ./... go -C examples vet ./... From 2de4f085fa92416d133c472ef6e0d53857e5a3ed Mon Sep 17 00:00:00 2001 From: Chris Miles Date: Sat, 1 Aug 2026 04:40:18 +0000 Subject: [PATCH 5/5] chore: expose documentation watcher --- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 3336e18..90b2519 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,3 @@ -.PHONY: help 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] } } @@ -24,3 +23,6 @@ vet: ##@analysis Run Go vet for every module. generate: ##@documentation Regenerate documentation examples and README content. go -C docs run ./examplegen go -C docs run ./readme + +docs-watch: ##@documentation Watch source changes and regenerate documentation. + sh docs/watcher.sh