docs: Update some docs

README.md

@@ -12,24 +12,20 @@ but feel free to try it out, or fork it!
 
 ## Features
 
-- Support for Insiders versions of projects (e.g. see [@pawamoy's insiders](https://pawamoy.github.io/insiders/))
 - [uv](https://github.com/astral-sh/uv) setup, with pre-defined `pyproject.toml`
+- Pre-configured tools for code formatting, quality analysis and testing:
+  [ruff](https://github.com/charliermarsh/ruff),
+  [mypy](https://github.com/python/mypy),
+  [safety](https://github.com/pyupio/safety)
+- Tests run with [pytest](https://github.com/pytest-dev/pytest) and plugins, with [coverage](https://github.com/nedbat/coveragepy) support
 - Documentation built with [MkDocs](https://github.com/mkdocs/mkdocs)
   ([Material theme](https://github.com/squidfunk/mkdocs-material)
   and "autodoc" [mkdocstrings plugin](https://github.com/mkdocstrings/mkdocstrings))
-- Pre-configured tools for code formatting, quality analysis and testing:
-    - [black](https://github.com/psf/black),
-    - [blacken-docs](https://github.com/adamchainz/blacken-docs),
-    - [ruff](https://github.com/charliermarsh/ruff),
-    - [mypy](https://github.com/python/mypy),
-    - [safety](https://github.com/pyupio/safety)
-- Tests run with [pytest](https://github.com/pytest-dev/pytest) and plugins, with [coverage](https://github.com/nedbat/coveragepy) support
 - Cross-platform tasks with [duty](https://github.com/pawamoy/duty)
 - Support for GitHub workflows
-- Python 3.8 or above
-- Auto-generated `CHANGELOG.md` from git commits (using Angular message style)
+- Auto-generated `CHANGELOG.md` from Git (conventional) commits
 - All licenses from [choosealicense.com](https://choosealicense.com/appendix/)
-- Makefile for convenience
+- Support for Insiders versions of projects (e.g. see [@pawamoy's insiders](https://pawamoy.github.io/insiders/))
 
 ## Quick setup and usage
 

project/Makefile.jinja

@@ -1,3 +1,7 @@
+# If you have `direnv` loaded in your shell, and allow it in the repository,
+# the `make` command will point at the `scripts/make` shell script.
+# This Makefile is just here to allow auto-completion in the terminal.
+
 actions = \
 	changelog \
 	check \
@@ -22,4 +26,4 @@ actions = \
 
 .PHONY: $(actions)
 $(actions):
-	@:
+	@bash scripts/make "$@"

project/scripts/make

@@ -5,19 +5,11 @@ export PYTHON_VERSIONS=${PYTHON_VERSIONS-3.8 3.9 3.10 3.11 3.12}
 exe=""
 prefix=""
 
-options() {
-    local shift_count=0
-    for arg in "$@"; do
-        if [[ "${arg}" =~ ^- || "${arg}" =~ ^.+= ]]; then
-            echo "${arg}"
-            ((shift_count++))
-        else
-            break
-        fi
-    done
-    return ${shift_count}
-}
 
+# Setup the development environment by installing dependencies
+# in multiple Python virtual environments with uv:
+# one venv per Python version in `.venvs/$py`,
+# and an additional default venv in `.venv`.
 setup() {
     if ! command -v uv &>/dev/null; then
         echo "make: setup: uv must be installed, see https://github.com/astral-sh/uv" >&2
@@ -37,6 +29,10 @@ setup() {
     uv pip install -r devdeps.txt
 }
 
+
+# Activate a Python virtual environments.
+# The annoying operating system also requires
+# that we set some global variables to help it find commands...
 activate() {
     local path
     if [ -f "$1/bin/activate" ]; then
@@ -53,6 +49,10 @@ activate() {
     return 1
 }
 
+
+# Run a command in all configured Python virtual environments.
+# We handle the case when the `PYTHON_VERSIONS` environment variable
+# is unset or empty, for robustness.
 multirun() {
     local cmd="$1"
     shift
@@ -66,10 +66,33 @@ multirun() {
     fi
 }
 
+
+# Run a command in the default Python virtual environment.
+# We rely on `multirun`'s handling of empty `PYTHON_VERSIONS`.
 singlerun() {
     PYTHON_VERSIONS= multirun "$@"
 }
 
+
+# Record options following a command name,
+# until a non-option argument is met or there are no more arguments.
+# Output each option on a new line, so the parent caller can store them in an array.
+# Return the number of times the parent caller must shift arguments.
+options() {
+    local shift_count=0
+    for arg in "$@"; do
+        if [[ "${arg}" =~ ^- || "${arg}" =~ ^.+= ]]; then
+            echo "${arg}"
+            ((shift_count++))
+        else
+            break
+        fi
+    done
+    return ${shift_count}
+}
+
+
+# Main function.
 main() {
     local cmd
     while [ $# -ne 0 ]; do
@@ -88,12 +111,13 @@ main() {
             exit $?
         fi
 
-        # All commands except run can use this.
-        # Some of them might print warnings/errors
-        # if options were given on the CLI.
+        # All commands except `run` and `multirun` can be chained on a single line.
+        # Some of them accept options in two formats: `-f`, `--flag` and `param=value`.
+        # Some of them don't, and will print warnings/errors if options were given.
         opts=($(options "$@")); shift $?
 
         case "${cmd}" in
+            # The following commands require special handling.
             help|"")
                 singlerun duty --list ;;
             setup)
@@ -102,15 +126,21 @@ main() {
                 multirun duty check-quality check-types check-docs
                 singlerun duty check-dependencies check-api
             ;;
+
+            # The following commands run in all venvs.
             check-quality|\
             check-docs|\
             check-types|\
             test)
                 multirun duty "${cmd}" "${opts[@]}" ;;
+
+            # The following commands run in the default venv only.
             *)
                 singlerun duty "${cmd}" "${opts[@]}" ;;
         esac
     done
 }
 
+
+# Execute the main function.
 main "$@"