remove zsh dependency; prettify makefile doc presentation

Author: reece

Makefile

@@ -6,11 +6,6 @@
 .DEFAULT_GOAL := help
 default: help
 
-ifeq ("","$(shell command -v zsh)")
-$(error "zsh not found; you must install zsh first")
-endif
-SHELL:=zsh -eu -o pipefail -o null_glob
-
 COLOR_RESET=\033[0m
 COLOR_CYAN_BOLD=\033[1;36m
 define INFO_MESSAGE
@@ -22,8 +17,7 @@ endef
 
 .PHONY: help
 help: ## Display help message
-	@uvx python -c "import re; \
-	[[print(f'✦ \033[36m{m[0]:<20}\033[0m {m[1]}') for m in re.findall(r'^([\sa-zA-Z_-]+):.*?## (.*)$$', open(makefile).read(), re.M)] for makefile in ('$(MAKEFILE_LIST)').strip().split()]" | sort
+	@./sbin/makefile-extract-documentation ${MAKEFILE_LIST}
 
 ############################################################################
 #= SETUP, INSTALLATION, PACKAGING
@@ -42,6 +36,12 @@ build: ## Build package
 	rm -fr dist
 	uv build
 
+.PHONY: publish
+publish: build ## publish package to PyPI
+	$(call INFO_MESSAGE, "Publishing package")
+	uv publish  # Requires UV_PUBLISH_TOKEN or Trusted Publishing setup
+
+
 ############################################################################
 #= FORMATTING, TESTING, AND CODE QUALITY
 
@@ -78,14 +78,15 @@ docs-test: ## Test if documentation can be built without warnings or errors
 .PHONY: clean
 clean:  ## Remove temporary and backup files
 	$(call INFO_MESSAGE, "Remove temporary and backup files")
-	rm -frv **/*~ **/*.bak
+	find . \( -name "*~" -o -name "*.bak" \) -exec rm -frv {} +
 
 .PHONY: cleaner
 cleaner: clean  ## Remove files and directories that are easily rebuilt
 	$(call INFO_MESSAGE, "Remove files and directories that are easily rebuilt")
 	rm -frv .cache .DS_Store .pytest_cache .ruff_cache build coverage.xml dist docs/_build site
-	rm -frv **/*.pyc **/__pycache__ **/*.egg-info
-	rm -frv **/*.orig **/*.rej
+	find . \( -name __pycache__ -type d \) -exec rm -frv {} +
+	find . \( -name "*.pyc" -o -name "*.egg-info" \) -exec rm -frv {} +
+	find . \( -name "*.orig" -o -name "*.rej" \) -exec rm -frv {} +
 
 .PHONY: cleanest
 cleanest: cleaner  ## Remove all files that can be rebuilt

sbin/makefile-extract-documentation

@@ -1,29 +1,23 @@
-#!/usr/bin/env perl
-# makefile-extract-documentation -- extract doc from a makefile
+#!/usr/bin/env python
+"""extract doc from a makefile"""
 
-# This script prints the header, up to the first empty line AND prints
-# line starting with #=, and indented by an optional number of >.
+# ############################################################################
+# #= BASIC USAGE
+#
+# .PHONY: help
+# help: ## Display help message
 
-my $print = 1;
-while (<>) {
-  next if ($. == 1 and m/^\#!/);
-  print if ($print or s/^\#=([>]*)\s+/'  ' x length($1)/e);
-  $print = 0 if m/^$/;
-}
+import fileinput
+import re
 
+BOLD = "\033[1m"
+UNDERLINE = "\033[4m"
+SECTION_COLOR = "\033[93m"
+RESET = "\033[0m"
+COMMAND_COLOR = "\033[36m"
 
-# <LICENSE>
-# Copyright 2021 Reece Hart ([email protected])
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-# </LICENSE>
+for line in fileinput.input():  # noqa: SIM115
+    if m := re.match(r"#= (.+)", line):
+        print(f"\n{BOLD}{UNDERLINE}{SECTION_COLOR}{m.group(1)}{RESET}")
+    elif m := re.match(r"([-\s\w]+):.+?##\s+(.+)", line):
+        print(f"{BOLD}{COMMAND_COLOR}{m.group(1):<20}{RESET}{m.group(2)}")