Infra: Refactor Makefile (#3514)

Author: hugovk

.github/workflows/render.yml

@@ -56,7 +56,7 @@ jobs:
         if: (github.ref == 'refs/heads/main') && (matrix.python-version == '3.x')
         uses: JamesIves/github-pages-deploy-action@v4
         with:
-          folder: build # Synchronise with Makefile -> OUTPUT_DIR
+          folder: build # Synchronise with Makefile -> BUILDDIR
           single-commit: true # Delete existing files
 
       - name: Purge CDN cache

Makefile

@@ -3,16 +3,18 @@
 # You can set these variables from the command line.
 PYTHON       = python3
 VENVDIR      = .venv
+# synchronise with render.yml -> deploy step
+BUILDDIR     = build
 SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
 BUILDER      = html
 JOBS         = 8
 SOURCES      =
-# synchronise with render.yml -> deploy step
-OUTPUT_DIR   = build
 SPHINXERRORHANDLING = -W --keep-going -w sphinx-warnings.txt
 
-ALLSPHINXOPTS = -b $(BUILDER) -j $(JOBS) \
-                $(SPHINXOPTS) $(SPHINXERRORHANDLING) peps $(OUTPUT_DIR) $(SOURCES)
+ALLSPHINXOPTS = -b $(BUILDER) \
+                -j $(JOBS) \
+                $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
+                peps $(BUILDDIR) $(SOURCES)
 
 ## html           to render PEPs to "pep-NNNN.html" files
 .PHONY: html
@@ -27,14 +29,17 @@ htmlview: html
 ## dirhtml        to render PEPs to "index.html" files within "pep-NNNN" directories
 .PHONY: dirhtml
 dirhtml: BUILDER = dirhtml
-dirhtml: venv
-	$(SPHINXBUILD) $(ALLSPHINXOPTS)
+dirhtml: html
 
-## check-links    to check validity of links within PEP sources
-.PHONY: check-links
+## linkcheck      to check validity of links within PEP sources
+.PHONY: linkcheck
 check-links: BUILDER = linkcheck
-check-links: venv
-	$(SPHINXBUILD) $(ALLSPHINXOPTS)
+check-links: html
+
+## check-links    (deprecated: use 'make linkcheck' alias instead)
+.PHONY: pages
+check-links: linkcheck
+	@echo "\033[0;33mWarning:\033[0;31m 'make check-links' \033[0;33mis deprecated, use\033[0;32m 'make linkcheck' \033[0;33malias instead\033[0m"
 
 ## clean          to remove the venv and build files
 .PHONY: clean

docs/build.rst

@@ -82,7 +82,7 @@ Check the validity of links within PEP sources (runs the `Sphinx linkchecker
 .. code-block:: shell
 
    python build.py --check-links
-   make check-links
+   make linkcheck
 
 
 ``build.py`` usage

readthedocs.yaml

@@ -6,7 +6,7 @@ build:
     python: "3.11"
 
   commands:
-    - make dirhtml JOBS=$(nproc) OUTPUT_DIR=_readthedocs/html
+    - make dirhtml JOBS=$(nproc) BUILDDIR=_readthedocs/html
 
 sphinx:
   builder: dirhtml