From 7d9b4d9fa500f5ca8abe7adb327bbbbd35dab6c9 Mon Sep 17 00:00:00 2001
From: Ross Patterson <me@rpatterson.net>
Date: Sat, 16 Aug 2025 12:04:49 -0700
Subject: [PATCH] [DEV] Makefile improvements (#1283)

* build(make): Defensive make settings best practice

I've been bitten by silent failures in make many times and these settings have spared me
that many times. I now use them religiously whenever possible.

* build(docs): Missed Sphinx issues, fail on warn

It would be nice to have these failures in CI. Is there a way to get the ReadTheDocs
integration to use these options?
---
 Makefile | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index 938e8fe7..d51d267c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,20 @@
+# Defensive settings for make:
+#     https://tech.davis-hansson.com/p/make/
+SHELL:=bash
+.ONESHELL:
+.SHELLFLAGS:=-eu -o pipefail -c
+.SILENT:
+.DELETE_ON_ERROR:
+MAKEFLAGS+=--warn-undefined-variables
+MAKEFLAGS+=--no-builtin-rules
+export PS1?=$$
+# Prefix echoed recipe commands with the recipe line number for debugging:
+export PS4?=:$$LINENO+
+
 # Get version related variables
-export DATE=$(shell date +'%Y.%m.%d')
-export DATE_COMMIT_COUNT=$(shell git rev-list --count HEAD --since="$(DATE) 00:00:00")
-export COMMIT_HASH=$(shell git rev-parse --short HEAD)
+export DATE:=$(shell date +'%Y.%m.%d')
+export DATE_COMMIT_COUNT:=$(shell git rev-list --count HEAD --since="$(DATE) 00:00:00")
+export COMMIT_HASH:=$(shell git rev-parse --short HEAD)
 
 # Set Local version to YYYY.MM.DD-<hash>
 export LOCAL_VERSION="$(DATE)+$(COMMIT_HASH)"
@@ -13,6 +26,15 @@ else
 	export PYPI_VERSION="$(DATE).post$(DATE_COMMIT_COUNT)"
 endif
 
+# Finished with `$(shell)`, echo recipe commands going forward
+.SHELLFLAGS+= -x
+
+
+### Top-level targets:
+
+.PHONY: all
+all: check_lint docs docker docker_ubuntu docker_gui
+
 lint:
 	python3 -m isort .
 	python3 -m black .
@@ -41,7 +63,7 @@ executable: clean
 	mv dist/ytdl-sub dist/ytdl-sub${EXEC_SUFFIX}
 docs:
 	REGENERATE_DOCS=1 pytest tests/unit/docgen/test_docgen.py
-	sphinx-build -M html docs/source/ docs/build/
+	sphinx-build --fail-on-warning --nitpicky -b html docs/source/ docs/build/
 clean:
 	rm -rf \
 		.pytest_cache/ \