From 77ef977c1598c222d64f0a1a4612769cf4c236f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Elias=20H=C3=A4u=C3=9Fler?= <e.haeussler@familie-redlich.de>
Date: Mon, 11 Aug 2025 10:39:24 +0200
Subject: [PATCH] [TASK] Migrate to PHP-based documentation rendering

---
 .github/workflows/cgl.yaml |  6 ++++++
 Documentation/Settings.cfg | 17 -----------------
 Documentation/genindex.rst |  7 -------
 Documentation/guides.xml   | 16 ++++++++++++++++
 composer.json              |  4 ++--
 docker-compose.yml         | 11 +++++------
 version-bumper.yaml        |  5 +----
 7 files changed, 30 insertions(+), 36 deletions(-)
 delete mode 100644 Documentation/Settings.cfg
 delete mode 100644 Documentation/genindex.rst
 create mode 100644 Documentation/guides.xml

diff --git a/.github/workflows/cgl.yaml b/.github/workflows/cgl.yaml
index d07eebbd..47fe258a 100644
--- a/.github/workflows/cgl.yaml
+++ b/.github/workflows/cgl.yaml
@@ -54,3 +54,9 @@ jobs:
       # Migration
       - name: Run Rector migration
         run: composer migration:rector -- --dry-run
+
+      # Documentation
+      - name: Check documentation build
+        run: |
+          mkdir -p .Build/docs
+          composer docs:build -- --no-progress --fail-on-log
diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg
deleted file mode 100644
index dacaa685..00000000
--- a/Documentation/Settings.cfg
+++ /dev/null
@@ -1,17 +0,0 @@
-[general]
-project = Handlebars
-release = 0.7.26
-copyright = since 2020 by coding. powerful. systems. CPS GmbH
-author = Elias Häußler
-
-[html_theme_options]
-project_home = https://extensions.typo3.org/extension/handlebars
-project_contact = https://typo3.slack.com/archives/C0281DBRFCZ
-project_issues = https://github.com/CPS-IT/handlebars/issues
-github_branch = main
-github_repository = CPS-IT/handlebars
-project_repository = https://github.com/CPS-IT/handlebars
-
-[intersphinx_mapping]
-t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/
-t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/
diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst
deleted file mode 100644
index 38a804f9..00000000
--- a/Documentation/genindex.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-..  include:: /Includes.rst.txt
-
-=====
-Index
-=====
-
-..  Sphinx will insert here the general index automatically.
diff --git a/Documentation/guides.xml b/Documentation/guides.xml
new file mode 100644
index 00000000..70370c76
--- /dev/null
+++ b/Documentation/guides.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+        links-are-relative="true"
+>
+    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+               project-home="https://extensions.typo3.org/extension/handlebars"
+               project-contact="https://typo3.slack.com/archives/C0281DBRFCZ"
+               project-repository="https://github.com/CPS-IT/handlebars"
+               project-issues="https://github.com/CPS-IT/handlebars/issues" edit-on-github-branch="main"
+               edit-on-github="CPS-IT/handlebars" typo3-core-preferred="stable"
+    />
+    <project title="Handlebars" release="0.7.26" copyright="since 2020 by coding. powerful. systems. CPS GmbH"/>
+    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
+    <inventory id="t3tsref" url="https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/"/>
+</guides>
diff --git a/composer.json b/composer.json
index c102bef8..12c11e6e 100644
--- a/composer.json
+++ b/composer.json
@@ -102,9 +102,9 @@
 			"@docs:build",
 			"@docs:open"
 		],
-		"docs:build": "docker-compose run --rm docs",
+		"docs:build": "docker compose run --rm docs",
 		"docs:cleanup": "rm -rf .Build/docs",
-		"docs:open": "open .Build/docs/Result/project/0.0.0/Index.html",
+		"docs:open": "open .Build/docs/Index.html",
 		"fix": [
 			"@fix:composer",
 			"@fix:editorconfig",
diff --git a/docker-compose.yml b/docker-compose.yml
index 36aa93a2..256b6300 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,9 +1,8 @@
-version: '3.6'
-
 services:
   docs:
-    image: ghcr.io/t3docs/render-documentation:develop
-    command: makehtml
+    image: ghcr.io/typo3-documentation/render-guides
+    entrypoint: ['/opt/guides/entrypoint.sh', '--config', 'Documentation', '--output', '/result']
+    pull_policy: always
     volumes:
-      - .:/PROJECT:ro
-      - .Build/docs:/RESULT
+      - .:/project:ro
+      - .Build/docs:/result
diff --git a/version-bumper.yaml b/version-bumper.yaml
index df40179c..964c15a4 100644
--- a/version-bumper.yaml
+++ b/version-bumper.yaml
@@ -1,9 +1,6 @@
 presets:
   - typo3-commit-guidelines
-  - name: typo3-extension
-    options:
-      # @todo Migrate to PHP-based documentation rendering
-      documentation: legacy
+  - typo3-extension
 
 releaseOptions:
   commitMessage: '[RELEASE] Release of EXT:handlebars {%version%}'