diff --git a/Build/.php-cs-fixer.dist.php b/Build/.php-cs-fixer.dist.php index 7bd02cda89..f28ca98280 100644 --- a/Build/.php-cs-fixer.dist.php +++ b/Build/.php-cs-fixer.dist.php @@ -14,7 +14,7 @@ ->setRules([ '@DoctrineAnnotation' => true, // @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 - '@PER-CS1.0' => true, + '@PER-CS1x0' => true, 'array_indentation' => true, 'array_syntax' => ['syntax' => 'short'], 'cast_spaces' => ['space' => 'none'], diff --git a/Makefile b/Makefile index b630fb6636..3aefe5856b 100644 --- a/Makefile +++ b/Makefile @@ -1,62 +1,130 @@ +# ============================================================================== +# TYPO3 Documentation - Makefile +# ============================================================================== +# Run `make` or `make help` to see available commands +# +# Prerequisites: +# - Docker (for docs rendering) +# - DDEV (for code generation tasks) +# ============================================================================== + +# ------------------------------------------------------------------------------ +# Configuration +# ------------------------------------------------------------------------------ +DOCKER_IMAGE := ghcr.io/typo3-documentation/render-guides:latest +DOCKER_USER := $(shell id -u):$(shell id -g) +DOCS_DIR := Documentation +DOCS_OUTPUT := Documentation-GENERATED-temp +COMPOSER_AUTOLOAD := .Build/vendor/autoload.php + +.DEFAULT_GOAL := help + +# ------------------------------------------------------------------------------ +# Dependency Checks +# ------------------------------------------------------------------------------ +.PHONY: check-dependencies +check-dependencies: + @if [ ! -f "$(COMPOSER_AUTOLOAD)" ]; then \ + echo ""; \ + echo "ERROR: Dependencies not installed."; \ + echo ""; \ + echo "Please run:"; \ + echo " make install"; \ + echo ""; \ + exit 1; \ + fi + +# ------------------------------------------------------------------------------ +# Help +# ------------------------------------------------------------------------------ .PHONY: help -help: ## Displays this list of targets with descriptions - @echo "The following commands are available:\n" - @grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}' - +help: ## Display available commands + @echo "Usage: make [target]\n" + @echo "Targets:" + @grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[32m%-20s\033[0m %s\n", $$1, $$2}' + +# ------------------------------------------------------------------------------ +# Documentation +# ------------------------------------------------------------------------------ .PHONY: docs -docs: ## Generate projects documentation (from "Documentation" directory) - mkdir -p Documentation-GENERATED-temp - - 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 +docs: ## Build documentation locally + mkdir -p $(DOCS_OUTPUT) + docker run --user $(DOCKER_USER) --rm --pull always -v "$(shell pwd)":/project -t $(DOCKER_IMAGE) --config=$(DOCS_DIR) + +.PHONY: docs-test +docs-test: ## Build documentation with strict validation (CI mode) + mkdir -p $(DOCS_OUTPUT) + docker run --user $(DOCKER_USER) --rm --pull always -v "$(shell pwd)":/project -t $(DOCKER_IMAGE) --config=$(DOCS_DIR) --no-progress --fail-on-log + +.PHONY: docs-open +docs-open: ## Open rendered documentation in browser + @if [ -f "$(DOCS_OUTPUT)/Index.html" ]; then \ + 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"; \ + else \ + echo "Documentation not found. Run 'make docs' first."; \ + fi + +# ------------------------------------------------------------------------------ +# Code Generation (requires DDEV) +# ------------------------------------------------------------------------------ +.PHONY: generate +generate: setup-typo3 codesnippets command-json ## Regenerate all auto-generated documentation -.PHONY: test-docs -test-docs: ## Test the documentation rendering - mkdir -p Documentation-GENERATED-temp +.PHONY: codesnippets +codesnippets: check-dependencies ## Regenerate PHP code snippets + ddev exec .Build/bin/typo3 codesnippet:create $(DOCS_DIR)/ - 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 +.PHONY: command-json +command-json: check-dependencies ## Regenerate console commands JSON + ddev exec .Build/bin/typo3 clinspector:gadget > $(DOCS_DIR)/ApiOverview/CommandControllers/commands.json + echo "" >> $(DOCS_DIR)/ApiOverview/CommandControllers/commands.json -.PHONY: generate -generate: setup-typo3 codesnippets command-json ## Regenerate automatic code documentation +# ------------------------------------------------------------------------------ +# Setup (requires DDEV) +# ------------------------------------------------------------------------------ +.PHONY: install +install: composer-update ## Install project dependencies -.PHONY: codesnippets -codesnippets: ## Regenerate code snippets - ddev exec .Build/bin/typo3 codesnippet:create Documentation/ +.PHONY: composer-update +composer-update: ## Update Composer dependencies + Build/Scripts/runTests.sh -s composerUpdate .PHONY: setup-typo3 -setup-typo3: ## Setup TYPO3 stub +setup-typo3: check-dependencies ## Initialize TYPO3 for documentation generation 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' -.PHONY: command-json -command-json: ## Regenerate JSON file containing all console commands - ddev exec .Build/bin/typo3 clinspector:gadget > Documentation/ApiOverview/CommandControllers/commands.json - echo "" >> Documentation/ApiOverview/CommandControllers/commands.json +# ------------------------------------------------------------------------------ +# Testing +# ------------------------------------------------------------------------------ +.PHONY: test +test: docs-test test-lint test-cgl test-yaml ## Run all tests .PHONY: test-lint -test-lint: ## Regenerate code snippets +test-lint: ## Check PHP syntax Build/Scripts/runTests.sh -s lint .PHONY: test-cgl -test-cgl: ## Regenerate code snippets - Build/Scripts/runTests.sh -s cgl +test-cgl: check-dependencies ## Check TYPO3 Coding Guidelines (dry-run) + Build/Scripts/runTests.sh -s cgl -n .PHONY: test-yaml -test-yaml: ## Regenerate code snippets +test-yaml: check-dependencies ## Validate YAML files Build/Scripts/runTests.sh -s yamlLint - -.PHONY: composerUpdate -composerUpdate: ## Update all dependencies (the composer.lock is not commited) - Build/Scripts/runTests.sh -s composerUpdate - -.PHONY: install -install: composerUpdate## Update all dependencies (the composer.lock is not commited) - -.PHONY: test -test: test-docs test-lint test-cgl test-yaml## Test the documentation rendering +# ------------------------------------------------------------------------------ +# Fixing +# ------------------------------------------------------------------------------ +.PHONY: fix +fix: fix-cgl ## Apply all automatic fixes .PHONY: fix-cgl -fix-cgl: ## Fix cgl +fix-cgl: check-dependencies ## Fix TYPO3 Coding Guidelines violations Build/Scripts/runTests.sh -s cgl -.PHONY: Fix all -fix: fix-cgl## Test the documentation rendering +# ------------------------------------------------------------------------------ +# Cleanup +# ------------------------------------------------------------------------------ +.PHONY: clean +clean: ## Remove generated documentation + rm -rf $(DOCS_OUTPUT) + @echo "Cleaned $(DOCS_OUTPUT)" diff --git a/composer.json b/composer.json index 0c9d7cb1c1..e2ec0a576f 100644 --- a/composer.json +++ b/composer.json @@ -4,6 +4,7 @@ "license": "OPL-1.0", "type": "typo3-cms-documentation", "require": { + "php": ">=8.2", "typo3/cms-core": "dev-main as 13.4" }, "require-dev": {