Makefile to generate documentation for a SPM package

Makefile

#!/bin/zsh -e -o pipefail

# THIS MAKEFILE GENERATES DOCUMENTATION FOR A PACKAGE.
# It assumes that your doc file is at Sources/<PackageName>/<PackageName>.docc/<PackageName>.md

GIT_USER := YourGitHubUser
PACKAGE_NAME := $(shell basename $(CURDIR))
PACKAGE_NAME_LOWER := $(shell echo $(PACKAGE_NAME) | tr '[:upper:]' '[:lower:]')
DOCC_DIR := Sources/$(PACKAGE_NAME)/$(PACKAGE_NAME).docc
DOCC_FILE := $(DOCC_DIR)/$(PACKAGE_NAME).md
GITHUB_DOCS_DIR := ./docs
GENERATED_DOCC_DIR := ./.build/docc

.PHONY: build docc requirebrew requirejq requirexcbeautify

targets:
	@printf "\033[1;36m%-15s\033[0m - %s\n" "  preview" "Generate HTML from docc and open on browser. Reload to refresh."
	@printf "\033[1;36m%-15s\033[0m - %s\n" "  doccarchive" "Generates a .doccarchive for distribution"
	@printf "\033[1;36m%-15s\033[0m - %s\n" "  github" "Generate documentation for GitHub"


build: requirexcbeautify
	xcodebuild build -scheme "$(PACKAGE_NAME)" -destination "platform=macOS,arch=arm64" -skipPackagePluginValidation | xcbeautify


preview: build check_docc
	open http://localhost:8080/documentation/$(PACKAGE_NAME_LOWER)
	xcrun docc preview \
	    $(DOCC_DIR) \
	    --additional-symbol-graph-dir .build
	@echo ""
	@echo "Generated docc preview"
	@echo "    Input: $(DOCC_DIR)"
	@echo "    Output: http://localhost:8080/documentation/$(PACKAGE_NAME)"


doccarchive: build check_docc
	mkdir -p $(GENERATED_DOCC_DIR)/$(PACKAGE_NAME).doccarchive
	xcrun docc convert $(DOCC_DIR) \
	    --fallback-display-name $(PACKAGE_NAME) \
	    --fallback-bundle-identifier dev.jano.$(PACKAGE_NAME) \
	    --fallback-bundle-version 1 \
	    --additional-symbol-graph-dir .build \
	    --output-dir $(GENERATED_DOCC_DIR)/$(PACKAGE_NAME).doccarchive
	@echo ""
	@echo "Generates a .doccarchive for distribution"
	@echo "    Input: $(DOCC_DIR)"
	@echo "    Output: $(GENERATED_DOCC_DIR)/$(PACKAGE_NAME).doccarchive"


github: build requirejq check_git_user check_docc
	rm -rf $(GITHUB_DOCS_DIR)
	mkdir -p $(GITHUB_DOCS_DIR)
	swift build
	DOCC_JSON_PRETTYPRINT=YES

	swift package \
 	    --allow-writing-to-directory $(GITHUB_DOCS_DIR) \
	    generate-documentation \
 	    --target $(PACKAGE_NAME) \
 	    --output-path $(GITHUB_DOCS_DIR) \
 	    --transform-for-static-hosting \
 	    --hosting-base-path $(PACKAGE_NAME) \
	    --emit-digest

	cat $(GITHUB_DOCS_DIR)/linkable-entities.json | jq '.[].referenceURL' -r | sort > $(GITHUB_DOCS_DIR)/all_identifiers.txt
	sort $(GITHUB_DOCS_DIR)/all_identifiers.txt | sed -e "s/doc:\/\/$(PACKAGE_NAME)\/documentation\///g" | sed -e "s/^/- \`\`/g" | sed -e 's/$$/``/g' > $(GITHUB_DOCS_DIR)/all_symbols.txt

	@echo ""
	@echo "GitHub HTML generated at $(GITHUB_DOCS_DIR)"
	@echo "Push to GitHub and open https://$(GIT_USER).github.io/$(PACKAGE_NAME)/documentation/$(PACKAGE_NAME_LOWER)/"

requirexcbeautify:
	@if ! command -v brew &> /dev/null; then echo "Please install xcbeautify using 'brew install xcbeautify'"; exit 1; fi


requirebrew:
	@if ! command -v brew &> /dev/null; then echo "Please install brew from https://brew.sh/"; exit 1; fi


requirejq: requirebrew
	@if ! command -v jq &> /dev/null; then echo "Please install jq using 'brew install jq'"; exit 1; fi

check_git_user:
	@if [ "$(GIT_USER)" = "YourGitHubUser" ]; then \
		echo "Error: You need to change GIT_USER in the Makefile"; \
		exit 1; \
	fi

check_docc:
	@if [ ! -f "$(DOCC_FILE)" ]; then \
		echo "Creating $(DOCC_FILE)"; \
		mkdir -p "$(DOCC_DIR)"; \
		echo "# ``$(PACKAGE_NAME)``\n" > "$(DOCC_FILE)"; \
		echo "My $(PACKAGE_NAME) library.\n" >> "$(DOCC_FILE)"; \
		echo "## Overview\n" >> "$(DOCC_FILE)"; \
		echo "Blah, blah, blah" >> "$(DOCC_FILE)"; \
		echo "I created a $(DOCC_FILE) for you at $(DOCC_FILE)."; \
	fi