Aligned docs checks between GitHub Actions and local development.

Author: nessita

.github/workflows/docs.yml

@@ -22,7 +22,9 @@ permissions:
 jobs:
   docs:
     runs-on: ubuntu-24.04
-    name: spelling
+    defaults:
+      run:
+        working-directory: docs
     timeout-minutes: 60
     steps:
       - name: Checkout
@@ -37,51 +39,10 @@ jobs:
           cache-dependency-path: 'docs/requirements.txt'
       - name: Install system spell checker
         run: sudo apt update && sudo apt install -y aspell aspell-en
-      - run: python -m pip install -r docs/requirements.txt
-      - name: Build docs
-        run: |
-          cd docs
-          sphinx-build -b spelling -n -q -W -d _build/doctrees -D language=en_US -j auto . _build/spelling
-
-  blacken-docs:
-    runs-on: ubuntu-latest
-    name: blacken-docs
-    timeout-minutes: 60
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.14'
-      - run: python -m pip install blacken-docs
-      - name: Build docs
-        run: |
-          cd docs
-          make black
-          RESULT=`cat _build/black/output.txt`
-          if [ "$RESULT" -gt 0 ]; then
-              echo "💥 📢 Code blocks in documentation must be reformatted with blacken-docs 📢 💥"
-          fi;
-          exit $RESULT
-
-  lint-docs:
-    runs-on: ubuntu-latest
-    name: lint-docs
-    timeout-minutes: 60
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.14'
-      - run: python -m pip install sphinx-lint
-      - name: Build docs
-        run: |
-          cd docs
-          make lint
+      - run: python -m pip install -r requirements.txt
+      - name: Lint
+        run: make lint
+      - name: Black
+        run: make black
+      - name: Spelling
+        run: SPHINXOPTS="-q -W" make spelling

docs/Makefile

@@ -171,16 +171,33 @@ spelling:
 
 black:
 	@mkdir -p $(BUILDDIR)/black
-	find . -name "*.txt" -not -path "./_build/*" -not -path "./_theme/*" \
+	@find . -name "*.txt" -not -path "./_build/*" -not -path "./_theme/*" \
 		| xargs blacken-docs --rst-literal-block; echo $$? > "$(BUILDDIR)/black/output.txt"
-	@echo
-	@echo "Code blocks reformatted"
+	@RESULT=`cat $(BUILDDIR)/black/output.txt`; \
+	if [ "$$RESULT" -gt 0 ]; then \
+		echo "💥 📢 Code blocks in documentation must be reformatted with blacken-docs 📢 💥"; \
+		exit $$RESULT; \
+	else \
+		echo "Code blocks in documentation are properly formatted ✅"; \
+	fi
 
 lint:
 	$(PYTHON) lint.py
 	@echo
 	@echo "Documentation lint complete."
 
-check: spelling black lint
-	@echo
-	@echo "Style and spelling checks completed."
+check:
+	@echo "=== Spelling check ==="; \
+	$(MAKE) --no-print-directory SPHINXOPTS="-q -W" spelling; SPELLING=$$?; \
+	echo ""; \
+	echo "=== Code formatting check ==="; \
+	$(MAKE) --no-print-directory black; BLACK=$$?; \
+	echo ""; \
+	echo "=== Lint check ==="; \
+	$(MAKE) --no-print-directory lint; LINT=$$?; \
+	echo ""; \
+	if [ $$SPELLING -ne 0 ] || [ $$BLACK -ne 0 ] || [ $$LINT -ne 0 ]; then \
+		echo "Some checks failed."; \
+		exit 1; \
+	fi; \
+	echo "All style and spelling checks passed."