janodev · July 17, 2024 17:17
diff --git a/Makefile b/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
	#!/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