Skip to content

Commit bae5ae0

Browse files
CybotTMfroemken
CybotTM
authored and
froemken
committed
Improve build tooling: fix CGL issues and enhance Makefile (#6239)
* fix(build): use non-deprecated PER-CS ruleset in php-cs-fixer Replace deprecated @PER-CS1.0 ruleset with @PER-CS1x0 as recommended by php-cs-fixer. The old ruleset triggers deprecation warnings during CGL checks. * fix(build): add PHP version requirement to composer.json Add explicit PHP >=8.2 requirement to satisfy php-cs-fixer's composer.json validation which expects a PHP version constraint. * refactor(build): improve Makefile structure and developer experience Major improvements to the build tooling: Structure: - Extract repeated values into variables (DOCKER_IMAGE, DOCS_DIR, etc.) - Organize targets into logical sections with headers - Add .DEFAULT_GOAL := help for better discoverability - Rename composerUpdate to composer-update for consistency Bug fixes: - Fix test-cgl running same command as fix-cgl (now uses -n dry-run flag) - Correct copy-pasted and inaccurate target descriptions New features: - Add check-dependencies guard with clear error message - Add clean target for removing generated files - Add docs-open target for quick preview in browser All dependent targets now provide helpful error messages when dependencies are not installed instead of cryptic failures.
1 parent 44e4f27 commit bae5ae0

File tree

3 files changed

+109
-40
lines changed

3 files changed

+109
-40
lines changed

‎Build/.php-cs-fixer.dist.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
->setRules([
1515
'@DoctrineAnnotation' => true,
1616
// @todo: Switch to @PER-CS2.0 once php-cs-fixer's todo list is done: https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/issues/7247
17-
'@PER-CS1.0' => true,
17+
'@PER-CS1x0' => true,
1818
'array_indentation' => true,
1919
'array_syntax' => ['syntax' => 'short'],
2020
'cast_spaces' => ['space' => 'none'],

‎Makefile‎

Lines changed: 107 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,130 @@
1+
# ==============================================================================
2+
# TYPO3 Documentation - Makefile
3+
# ==============================================================================
4+
# Run `make` or `make help` to see available commands
5+
#
6+
# Prerequisites:
7+
# - Docker (for docs rendering)
8+
# - DDEV (for code generation tasks)
9+
# ==============================================================================
10+
11+
# ------------------------------------------------------------------------------
12+
# Configuration
13+
# ------------------------------------------------------------------------------
14+
DOCKER_IMAGE := ghcr.io/typo3-documentation/render-guides:latest
15+
DOCKER_USER := $(shell id -u):$(shell id -g)
16+
DOCS_DIR := Documentation
17+
DOCS_OUTPUT := Documentation-GENERATED-temp
18+
COMPOSER_AUTOLOAD := .Build/vendor/autoload.php
19+
20+
.DEFAULT_GOAL := help
21+
22+
# ------------------------------------------------------------------------------
23+
# Dependency Checks
24+
# ------------------------------------------------------------------------------
25+
.PHONY: check-dependencies
26+
check-dependencies:
27+
@if [ ! -f "$(COMPOSER_AUTOLOAD)" ]; then \
28+
echo ""; \
29+
echo "ERROR: Dependencies not installed."; \
30+
echo ""; \
31+
echo "Please run:"; \
32+
echo " make install"; \
33+
echo ""; \
34+
exit 1; \
35+
fi
36+
37+
# ------------------------------------------------------------------------------
38+
# Help
39+
# ------------------------------------------------------------------------------
140
.PHONY: help
2-
help: ## Displays this list of targets with descriptions
3-
@echo "The following commands are available:\n"
4-
@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
5-
41+
help: ## Display available commands
42+
@echo "Usage: make [target]\n"
43+
@echo "Targets:"
44+
@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[32m%-20s\033[0m %s\n", $$1, $$2}'
45+
46+
# ------------------------------------------------------------------------------
47+
# Documentation
48+
# ------------------------------------------------------------------------------
649
.PHONY: docs
7-
docs: ## Generate projects documentation (from "Documentation" directory)
8-
mkdir -p Documentation-GENERATED-temp
9-
10-
docker run --user $(shell id -u):$(shell id -g) --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
50+
docs: ## Build documentation locally
51+
mkdir -p $(DOCS_OUTPUT)
52+
docker run --user $(DOCKER_USER) --rm --pull always -v "$(shell pwd)":/project -t $(DOCKER_IMAGE) --config=$(DOCS_DIR)
53+
54+
.PHONY: docs-test
55+
docs-test: ## Build documentation with strict validation (CI mode)
56+
mkdir -p $(DOCS_OUTPUT)
57+
docker run --user $(DOCKER_USER) --rm --pull always -v "$(shell pwd)":/project -t $(DOCKER_IMAGE) --config=$(DOCS_DIR) --no-progress --fail-on-log
58+
59+
.PHONY: docs-open
60+
docs-open: ## Open rendered documentation in browser
61+
@if [ -f "$(DOCS_OUTPUT)/Index.html" ]; then \
62+
xdg-open "$(DOCS_OUTPUT)/Index.html" 2>/dev/null || open "$(DOCS_OUTPUT)/Index.html" 2>/dev/null || echo "Open $(DOCS_OUTPUT)/Index.html in your browser"; \
63+
else \
64+
echo "Documentation not found. Run 'make docs' first."; \
65+
fi
66+
67+
# ------------------------------------------------------------------------------
68+
# Code Generation (requires DDEV)
69+
# ------------------------------------------------------------------------------
70+
.PHONY: generate
71+
generate: setup-typo3 codesnippets command-json ## Regenerate all auto-generated documentation
1172

12-
.PHONY: test-docs
13-
test-docs: ## Test the documentation rendering
14-
mkdir -p Documentation-GENERATED-temp
73+
.PHONY: codesnippets
74+
codesnippets: check-dependencies ## Regenerate PHP code snippets
75+
ddev exec .Build/bin/typo3 codesnippet:create $(DOCS_DIR)/
1576

16-
docker run --user $(shell id -u):$(shell id -g) --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log
77+
.PHONY: command-json
78+
command-json: check-dependencies ## Regenerate console commands JSON
79+
ddev exec .Build/bin/typo3 clinspector:gadget > $(DOCS_DIR)/ApiOverview/CommandControllers/commands.json
80+
echo "" >> $(DOCS_DIR)/ApiOverview/CommandControllers/commands.json
1781

18-
.PHONY: generate
19-
generate: setup-typo3 codesnippets command-json ## Regenerate automatic code documentation
82+
# ------------------------------------------------------------------------------
83+
# Setup (requires DDEV)
84+
# ------------------------------------------------------------------------------
85+
.PHONY: install
86+
install: composer-update ## Install project dependencies
2087

21-
.PHONY: codesnippets
22-
codesnippets: ## Regenerate code snippets
23-
ddev exec .Build/bin/typo3 codesnippet:create Documentation/
88+
.PHONY: composer-update
89+
composer-update: ## Update Composer dependencies
90+
Build/Scripts/runTests.sh -s composerUpdate
2491

2592
.PHONY: setup-typo3
26-
setup-typo3: ## Setup TYPO3 stub
93+
setup-typo3: check-dependencies ## Initialize TYPO3 for documentation generation
2794
ddev exec '.Build/bin/typo3 setup --driver=sqlite --username=db --password=db --admin-username=john-doe --admin-user-password="John-Doe-1701D." --admin-email="john.doe@example.com" --project-name="TYPO3 Docs" --no-interaction --server-type=apache --force'
2895

29-
.PHONY: command-json
30-
command-json: ## Regenerate JSON file containing all console commands
31-
ddev exec .Build/bin/typo3 clinspector:gadget > Documentation/ApiOverview/CommandControllers/commands.json
32-
echo "" >> Documentation/ApiOverview/CommandControllers/commands.json
96+
# ------------------------------------------------------------------------------
97+
# Testing
98+
# ------------------------------------------------------------------------------
99+
.PHONY: test
100+
test: docs-test test-lint test-cgl test-yaml ## Run all tests
33101

34102
.PHONY: test-lint
35-
test-lint: ## Regenerate code snippets
103+
test-lint: ## Check PHP syntax
36104
Build/Scripts/runTests.sh -s lint
37105

38106
.PHONY: test-cgl
39-
test-cgl: ## Regenerate code snippets
40-
Build/Scripts/runTests.sh -s cgl
107+
test-cgl: check-dependencies ## Check TYPO3 Coding Guidelines (dry-run)
108+
Build/Scripts/runTests.sh -s cgl -n
41109

42110
.PHONY: test-yaml
43-
test-yaml: ## Regenerate code snippets
111+
test-yaml: check-dependencies ## Validate YAML files
44112
Build/Scripts/runTests.sh -s yamlLint
45113

46-
47-
.PHONY: composerUpdate
48-
composerUpdate: ## Update all dependencies (the composer.lock is not commited)
49-
Build/Scripts/runTests.sh -s composerUpdate
50-
51-
.PHONY: install
52-
install: composerUpdate## Update all dependencies (the composer.lock is not commited)
53-
54-
.PHONY: test
55-
test: test-docs test-lint test-cgl test-yaml## Test the documentation rendering
114+
# ------------------------------------------------------------------------------
115+
# Fixing
116+
# ------------------------------------------------------------------------------
117+
.PHONY: fix
118+
fix: fix-cgl ## Apply all automatic fixes
56119

57120
.PHONY: fix-cgl
58-
fix-cgl: ## Fix cgl
121+
fix-cgl: check-dependencies ## Fix TYPO3 Coding Guidelines violations
59122
Build/Scripts/runTests.sh -s cgl
60123

61-
.PHONY: Fix all
62-
fix: fix-cgl## Test the documentation rendering
124+
# ------------------------------------------------------------------------------
125+
# Cleanup
126+
# ------------------------------------------------------------------------------
127+
.PHONY: clean
128+
clean: ## Remove generated documentation
129+
rm -rf $(DOCS_OUTPUT)
130+
@echo "Cleaned $(DOCS_OUTPUT)"

‎composer.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"license": "OPL-1.0",
55
"type": "typo3-cms-documentation",
66
"require": {
7+
"php": ">=8.2",
78
"typo3/cms-core": "^13.4"
89
},
910
"require-dev": {

0 commit comments

Comments
 (0)