feat: enhance docs-related make targets with changed-files focus

EdwardAngert · EdwardAngert · commit 08dc7937afb4 · 2025-04-24T10:45:58.000-04:00
- Add detection of changed markdown files in the docs directory
- Make lint/docs focus on changed files by default
- Add --all option to check all files instead of just changed ones
- Update Vale style checking to only validate changed files
- Improve message clarity for all documentation targets
diff --git a/Makefile b/Makefile
@@ -66,6 +66,10 @@ MOST_GO_SRC_FILES := $(shell \
 )
 # All the shell files in the repo, excluding ignored files.
 SHELL_SRC_FILES := $(shell find . $(FIND_EXCLUSIONS) -type f -name '*.sh')
+# All markdown files in docs directory, used to determine if docs targets should run
+DOCS_MD_FILES := $(shell find ./docs $(FIND_EXCLUSIONS) -type f -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
+# Changed markdown files (if in a git repo), otherwise empty
+DOCS_CHANGED_FILES := $(shell git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep -E '^docs/.*\.md$$' 2>/dev/null || echo "")
 
 # Ensure we don't use the user's git configs which might cause side-effects
 GIT_FLAGS = GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
@@ -501,13 +505,54 @@ endif
 .PHONY: fmt/shfmt
 
 fmt/markdown: node_modules/.installed
-	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/markdown$(RESET)"
-	pnpm format-docs
+	@if [ "$(DOCS_MD_FILES)" -gt 0 ]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/markdown$(RESET)"; \
+		if echo "$(MAKEFLAGS)" | grep -q "all"; then \
+			echo "Formatting all documentation files..."; \
+			pnpm format-docs; \
+		else \
+			if [ -n "$(DOCS_CHANGED_FILES)" ]; then \
+				echo "Formatting changed files only: $(DOCS_CHANGED_FILES)"; \
+				pnpm exec markdown-table-formatter $(DOCS_CHANGED_FILES) 2>/dev/null || echo "No tables found to format"; \
+			else \
+				echo "No changed files detected, running standard format..."; \
+				pnpm format-docs; \
+			fi; \
+		fi; \
+	else \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/markdown$(RESET) (skipped - no docs files)"; \
+	fi
 .PHONY: fmt/markdown
 
 lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown
 .PHONY: lint
 
+# Check document style with Vale (optional, opt-in, --all to check all files)
+lint/docs-style: node_modules/.installed
+	@if [ "$(DOCS_MD_FILES)" -gt 0 ]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)lint/docs-style$(RESET)"; \
+		if command -v vale >/dev/null 2>&1; then \
+			if echo "$(MAKEFLAGS)" | grep -q "all"; then \
+				echo "Checking all documentation files..."; \
+				vale --no-exit --config=.github/docs/vale/.vale.ini docs/; \
+			else \
+				if [ -n "$(DOCS_CHANGED_FILES)" ]; then \
+					echo "Checking changed files only: $(DOCS_CHANGED_FILES)"; \
+					vale --no-exit --config=.github/docs/vale/.vale.ini $(DOCS_CHANGED_FILES); \
+				else \
+					echo "No changed files detected, checking representative files..."; \
+					vale --no-exit --config=.github/docs/vale/.vale.ini docs/README.md docs/index.md 2>/dev/null || echo "No representative files found"; \
+				fi; \
+			fi; \
+		else \
+			echo "Vale is an optional tool for style checking."; \
+			echo "If you want to install it: brew install vale (or see https://vale.sh)"; \
+		fi; \
+	else \
+		echo "$(GREEN)==>$(RESET) $(BOLD)lint/docs-style$(RESET) (skipped - no docs files)"; \
+	fi
+.PHONY: lint/docs-style
+
 lint/site-icons:
 	./scripts/check_site_icons.sh
 .PHONY: lint/site-icons
@@ -540,9 +585,54 @@ lint/helm:
 .PHONY: lint/helm
 
 lint/markdown: node_modules/.installed
-	pnpm lint-docs
+	@if [ "$(DOCS_MD_FILES)" -gt 0 ]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)lint/markdown$(RESET)"; \
+		if echo "$(MAKEFLAGS)" | grep -q "all"; then \
+			echo "Checking all documentation files..."; \
+			pnpm lint-docs; \
+		else \
+			if [ -n "$(DOCS_CHANGED_FILES)" ]; then \
+				echo "Checking changed files only: $(DOCS_CHANGED_FILES)"; \
+				pnpm exec markdownlint-cli2 $(DOCS_CHANGED_FILES); \
+			else \
+				echo "No changed files detected, running standard lint..."; \
+				pnpm lint-docs; \
+			fi; \
+		fi; \
+	else \
+		echo "$(GREEN)==>$(RESET) $(BOLD)lint/markdown$(RESET) (skipped - no docs files)"; \
+	fi
 .PHONY: lint/markdown
 
+# Comprehensive documentation check (--all to check all files, otherwise only changed files)
+lint/docs: lint/markdown
+	@if [ "$(DOCS_MD_FILES)" -gt 0 ]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)lint/docs$(RESET)"; \
+		echo "Checking for broken links in markdown files..."; \
+		if command -v lychee >/dev/null 2>&1; then \
+			if echo "$(MAKEFLAGS)" | grep -q "all"; then \
+				echo "Checking all documentation files..."; \
+				lychee --config .github/docs/.lycheeignore docs/**/*.md; \
+			else \
+				if [ -n "$(DOCS_CHANGED_FILES)" ]; then \
+					echo "Checking changed files only: $(DOCS_CHANGED_FILES)"; \
+					lychee --config .github/docs/.lycheeignore $(DOCS_CHANGED_FILES); \
+				else \
+					echo "No changed files detected, checking representative files..."; \
+					lychee --config .github/docs/.lycheeignore docs/README.md docs/index.md; \
+				fi; \
+			fi; \
+		else \
+			echo "Lychee not found for link checking. Install with 'cargo install lychee' or see https://github.com/lycheeverse/lychee"; \
+		fi; \
+		echo ""; \
+		echo "To run additional style checks, use: make lint/docs-style"; \
+		echo "To check all files (not just changed ones), use: make lint/docs --all"; \
+	else \
+		echo "$(GREEN)==>$(RESET) $(BOLD)lint/docs$(RESET) (skipped - no docs files)"; \
+	fi
+.PHONY: lint/docs
+
 # All files generated by the database should be added here, and this can be used
 # as a target for jobs that need to run after the database is generated.
 DB_GEN_FILES := \
