From 06b20b5c384e17667d8245321d80d8f953918813 Mon Sep 17 00:00:00 2001
From: bibajz <libas@acco.cz>
Date: Sun, 4 Aug 2024 11:23:12 +0200
Subject: [PATCH] Remove GNU make-specific directive from Doc/Makefile

`define` - https://www.gnu.org/software/make/manual/html_node/Multi_002dLine.html -
is a GNU make extension not generally supported by other makes.

Introduce `UV` variable to accomodate for the case when `uv` is not
in `PATH`.

Remove the

```bash
$ python -m $(1) --version >/dev/null
```

commands that can prevent the installation of a package when it's
already present.

The rationale is this approach is really fragile, for multiple
reasons.

Firstly, it works on packages defining `__main__.py` module, there-
fore as an example, `anyio==4.4.0` package, even if installed, would
output:

```bash
$ /tmp/venv/bin/python -m anyio >/dev/null
/tmp/venv/bin/python: No module named anyio.__main__; 'anyio' is a package and cannot be directly executed
$ echo $?
1
```

Secondly, unlike package installation, which is insensitive to
capitalization as well as `-`/`_` separators - https://packaging.python.org/en/latest/specifications/name-normalization/#names-and-normalization -
module names are sensitive to naming, meaning this may happen
(and indeed happened in bc37ac7b440b5e816f0b3915b830404290522603)

```bash
$ /tmp/venv/bin/python -m sphinx-autobuild --help >/dev/null
/tmp/venv/bin/python: No module named sphinx-autobuild
$ echo $?
1
$ /tmp/venv/bin/python -m sphinx_autobuild --help >/dev/null
$ echo $?
0
```

And lastly, name of the package may not be the same as its contents
that are subsequently imported. Consider `PyYAML==6.0.1`, whose contents
are importable from the `yaml` namespace - https://pyyaml.org/wiki/PyYAMLDocumentation

```bash
$ /tmp/venv/bin/python -m pyyaml >/dev/null
/tmp/venv/bin/python: No module named pyyaml
$ /tmp/venv/bin/python -m yaml >/dev/null
/tmp/venv/bin/python: No module named yaml.__main__; 'yaml' is a package and cannot be directly executed
```
---
 Doc/Makefile | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/Doc/Makefile b/Doc/Makefile
index c70768754834dd..b2ee3fe7d28ed0 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -6,6 +6,7 @@
 # You can set these variables from the command line.
 PYTHON       = python3
 VENVDIR      = ./venv
+UV           = uv
 SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
 BLURB        = PATH=$(VENVDIR)/bin:$$PATH blurb
 JOBS         = auto
@@ -150,14 +151,10 @@ gettext: build
 htmlview: html
 	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
 
-.PHONY: ensure-sphinx-autobuild
-ensure-sphinx-autobuild: venv
-	$(call ensure_package,sphinx-autobuild)
-
 .PHONY: htmllive
 htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
 htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0
-htmllive: ensure-sphinx-autobuild html
+htmllive: _ensure-sphinx-autobuild html
 
 .PHONY: clean
 clean: clean-venv
@@ -174,15 +171,15 @@ venv:
 		echo "To recreate it, remove it first with \`make clean-venv'."; \
 	else \
 		echo "Creating venv in $(VENVDIR)"; \
-		if uv --version > /dev/null; then \
-			uv venv $(VENVDIR); \
-			VIRTUAL_ENV=$(VENVDIR) uv pip install -r $(REQUIREMENTS); \
+		if $(UV) --version >/dev/null 2>&1; then \
+			$(UV) venv $(VENVDIR); \
+			VIRTUAL_ENV=$(VENVDIR) $(UV) pip install -r $(REQUIREMENTS); \
 		else \
 			$(PYTHON) -m venv $(VENVDIR); \
 			$(VENVDIR)/bin/python3 -m pip install --upgrade pip; \
 			$(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \
-			echo "The venv has been created in the $(VENVDIR) directory"; \
 		fi; \
+		echo "The venv has been created in the $(VENVDIR) directory"; \
 	fi
 
 .PHONY: dist
@@ -240,17 +237,24 @@ dist:
 	rm -r dist/python-$(DISTVERSION)-docs-texinfo
 	rm dist/python-$(DISTVERSION)-docs-texinfo.tar
 
-define ensure_package
-	if uv --version > /dev/null; then \
-		$(VENVDIR)/bin/python3 -m $(1) --version > /dev/null || VIRTUAL_ENV=$(VENVDIR) uv pip install $(1); \
+.PHONY: _ensure-package
+_ensure-package: venv
+	if $(UV) --version >/dev/null 2>&1; then \
+		VIRTUAL_ENV=$(VENVDIR) $(UV) pip install $(PACKAGE); \
 	else \
-		$(VENVDIR)/bin/python3 -m $(1) --version > /dev/null || $(VENVDIR)/bin/python3 -m pip install $(1); \
+		$(VENVDIR)/bin/python3 -m pip install $(PACKAGE); \
 	fi
-endef
+
+.PHONY: _ensure-pre-commit
+_ensure-pre-commit:
+	make _ensure-package PACKAGE=pre-commit
+
+.PHONY: _ensure-sphinx-autobuild
+_ensure-sphinx-autobuild:
+	make _ensure-package PACKAGE=sphinx-autobuild
 
 .PHONY: check
-check: venv
-	$(call ensure_package,pre_commit)
+check: _ensure-pre-commit
 	$(VENVDIR)/bin/python3 -m pre_commit run --all-files
 
 .PHONY: serve