From 69e1d9603e4aceaf1c0e84ae0c4ed3dfdcf64bdd Mon Sep 17 00:00:00 2001
From: Matthew Foster Walsh <15671892+mfosterw@users.noreply.github.com>
Date: Tue, 23 Sep 2025 10:46:11 -0600
Subject: [PATCH] Added help command to sphinx Makefile (#6024)

Co-authored-by: Bruno Alla <alla.brunoo@gmail.com>
---
 docs/Makefile                               | 14 ++++++++------
 {{cookiecutter.project_slug}}/docs/Makefile |  8 ++++----
 {{cookiecutter.project_slug}}/docs/make.bat |  6 +++---
 3 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index fec1fc965..5a9c4479c 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -3,24 +3,21 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = uv run sphinx-build
+SPHINXBUILD   = uv run --group docs sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-.PHONY: help clean html livehtml linkcheck
+.PHONY: help clean livehtml linkcheck
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "html        Build the docs as HTML"
 	@awk '/^#/{c=substr($$0,3);next}c&&/^[[:alpha:]][[:alnum:]_-]+:/{print substr($$1,1,index($$1,":")),c}1{c=0}' $(MAKEFILE_LIST) | column -s: -t
 
 # Clean the build output
 clean:
 	-rm -rf $(BUILDDIR)/*
 
-# Build the HTML docs
-html:
-	$(SPHINXBUILD) -b html $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
-
 # Build and serve docs with live reload
 livehtml:
 	sphinx-autobuild -b html --port 9000 --watch . -c . $(SOURCEDIR) $(BUILDDIR)/html
@@ -31,3 +28,8 @@ linkcheck:
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .
diff --git a/{{cookiecutter.project_slug}}/docs/Makefile b/{{cookiecutter.project_slug}}/docs/Makefile
index 9e0e4d6c0..cf080e476 100644
--- a/{{cookiecutter.project_slug}}/docs/Makefile
+++ b/{{cookiecutter.project_slug}}/docs/Makefile
@@ -13,11 +13,11 @@ APP = /app
 APP = ../{{cookiecutter.project_slug}}
 {% endif %}
 
-.PHONY: html livehtml apidocs Makefile
+.PHONY: help livehtml apidocs Makefile
 
-# Put it first so that "make" without argument is like "make html".
-html:
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .
 
 # Build, watch and serve docs with live reload
 livehtml:
diff --git a/{{cookiecutter.project_slug}}/docs/make.bat b/{{cookiecutter.project_slug}}/docs/make.bat
index fbf6eb45f..c57e5829c 100644
--- a/{{cookiecutter.project_slug}}/docs/make.bat
+++ b/{{cookiecutter.project_slug}}/docs/make.bat
@@ -12,7 +12,7 @@ set SOURCEDIR=_source
 set BUILDDIR=_build
 set APP=..\{{cookiecutter.project_slug}}
 
-if "%1" == "" goto html
+if "%1" == "" goto help
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -39,8 +39,8 @@ GOTO :EOF
 sphinx-apidoc -o %SOURCEDIR%/api %APP%
 GOTO :EOF
 
-:html
-%SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
 popd