[TASK] Switch the documentation to PHP-based rendering (#1190)

Command for rendering:

    ./Build/Scripts/runTests.sh -s docsGenerate

or just:

    composer docs:generate

The reference to the TYPO3 Documentation Rendering Guide was adjusted as the Quickstart page does not exist anymore.

Additionally, the genindex isn't supported anymore. It is planned to consider the `index` directive in the global search on docs.typo3.org.

Resolves: #1189

.github/workflows/ci.yml

@@ -297,3 +297,13 @@ jobs:
           - typo3-version: "^12.4"
             php-version: "8.3"
             composer-dependencies: highest
+  documentation:
+    name: Documentation
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Test if the documentation will render without warnings
+        run: |
+          docker run --rm --pull always -v $(pwd):/project \
+             ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log

Build/Scripts/runTests.sh

@@ -433,7 +433,7 @@ mkdir -p .Build/public/typo3temp/var/tests
 
 IMAGE_PHP="ghcr.io/sbuerk/demo-core-testing-$(echo "php${PHP_VERSION}" | sed -e 's/\.//'):latest"
 IMAGE_ALPINE="docker.io/alpine:3.8"
-IMAGE_DOCS="ghcr.io/t3docs/render-documentation:latest"
+IMAGE_DOCS="ghcr.io/typo3-documentation/render-guides:latest"
 IMAGE_MARIADB="docker.io/mariadb:${DBMS_VERSION}"
 IMAGE_MYSQL="docker.io/mysql:${DBMS_VERSION}"
 IMAGE_POSTGRES="docker.io/postgres:${DBMS_VERSION}-alpine"
@@ -516,22 +516,8 @@ case ${TEST_SUITE} in
         SUITE_EXIT_CODE=$?
         ;;
     docsGenerate)
-        # @todo contact the documentation team for a future rootles podman version
+        ${CONTAINER_BIN} run --rm --pull always -v "$(pwd)":/project -it ${IMAGE_DOCS} --config=Documentation --fail-on-log
-        if [ "${CONTAINER_BIN}" == "podman" ]; then
+        SUITE_EXIT_CODE=$?
-            echo "-s docsGenerate is not usable with -b podman"
-            echo "TYPO3 Documentation Team needs to deal with this, and we will"
-            echo "see if the upcoming php based documentation rendering container"
-            echo "will support podman out-of-the-box"
-            echo ""
-            echo "Please use -b docker -s docsGenerate"
-            SUITE_EXIT_CODE=1
-        else
-            ${CONTAINER_BIN} run --rm ${IMAGE_DOCS} show-shell-commands > generate-documentation.sh
-            echo 'dockrun_t3rd makehtml' >> generate-documentation.sh
-            bash generate-documentation.sh
-            rm -Rf generate-documentation.sh
-            SUITE_EXIT_CODE=$?
-        fi
         ;;
     functional)
         [ -z "${TEST_FILE}" ] && TEST_FILE="Tests/Functional"

Documentation/Documentation.rst

@@ -19,4 +19,4 @@ automatically.
 
 .. seealso::
 
-   For further details read the :doc:`TYPO3 Documentation Rendering Guide <h2document:RenderingDocs/Quickstart>`.
+   For further details read the :ref:`TYPO3 Documentation Rendering Guide <h2document:docs-contribute-git-docker>`.

Documentation/Includes.rst.txt

@@ -1,34 +1 @@
-.. More information about this file:
+.. You can put central messages to display on all pages here
-   https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt
-
-.. ----------
-.. text roles
-.. ----------
-
-.. role:: aspect(emphasis)
-.. role:: bash(code)
-.. role:: html(code)
-.. role:: js(code)
-.. role:: php(code)
-.. role:: rst(code)
-.. role:: sep(strong)
-.. role:: sql(code)
-
-.. role:: tsconfig(code)
-   :class: typoscript
-
-.. role:: typoscript(code)
-.. role:: xml(code)
-   :class: html
-
-.. role:: yaml(code)
-
-.. default-role:: code
-
-.. ---------
-.. highlight
-.. ---------
-
-.. By default, code blocks use automatically detected syntax highlighting
-
-.. highlight:: guess

Documentation/Index.rst

@@ -58,4 +58,3 @@ continuous integration.
    :hidden:
 
    Sitemap
-   genindex

Documentation/Settings.cfg

@@ -1,62 +0,0 @@
-# More information about this file:
-# https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#settings-cfg
-
-[general]
-
-project     = TYPO3 EXT:tea
-version     = 3.1
-release     = 3.1.0
-copyright   = since 2013 by the TYPO3 contributors
-
-[html_theme_options]
-
-# "Edit on GitHub" button
-github_repository    = TYPO3-Documentation/tea
-github_branch        = main
-
-# Footer links
-project_home         = https://extensions.typo3.org/extension/tea
-project_contact      = mailto:typo3-coding@oliverklee.de
-project_repository   = https://github.com/FriendsOfTYPO3/tea
-project_issues       = https://github.com/FriendsOfTYPO3/tea/issues
-project_discussions  =
-
-use_opensearch       =
-
-[intersphinx_mapping]
-
-# Official TYPO3 manuals
-h2document     = https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
-# t3cheatsheets  = https://docs.typo3.org/m/typo3/docs-cheatsheets/main/en-us/
-# t3contribute   = https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/
-# t3coreapi      = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/
-# t3docteam      = https://docs.typo3.org/m/typo3/team-t3docteam/main/en-us/
-# t3editors      = https://docs.typo3.org/m/typo3/tutorial-editors/main/en-us/
-# t3extbasebook  = https://docs.typo3.org/m/typo3/book-extbasefluid/main/en-us/
-# t3extexample   = https://docs.typo3.org/m/typo3/guide-example-extension-manual/main/en-us/
-# t3home         = https://docs.typo3.org/
-# t3install      = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/
-# t3l10n         = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/
-# t3sitepackage  = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/
-# t3start        = https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/
-# t3tca          = https://docs.typo3.org/m/typo3/reference-tca/main/en-us/
-# t3templating   = https://docs.typo3.org/m/typo3/tutorial-templating/main/en-us/
-# t3translate    = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/
-# t3tsconfig     = https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/
-# t3tsref        = https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/
-# t3ts45         = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/main/en-us/
-# t3viewhelper   = https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/
-# t3upgrade      = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/
-
-# TYPO3 system extensions
-# ext_adminpanel     = https://docs.typo3.org/c/typo3/cms-adminpanel/main/en-us/
-# ext_core           = https://docs.typo3.org/c/typo3/cms-core/main/en-us/
-# ext_dashboard      = https://docs.typo3.org/c/typo3/cms-dashboard/main/en-us/
-# ext_felogin        = https://docs.typo3.org/c/typo3/cms-felogin/main/en-us/
-# ext_form           = https://docs.typo3.org/c/typo3/cms-form/main/en-us/
-# ext_fsc            = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/main/en-us/
-# ext_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/main/en-us/
-# ext_rte_ckeditor   = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/
-# ext_scheduler      = https://docs.typo3.org/c/typo3/cms-scheduler/main/en-us/
-# ext_seo            = https://docs.typo3.org/c/typo3/cms-seo/main/en-us/
-# ext_workspaces     = https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/

Documentation/genindex.rst

@@ -1,7 +0,0 @@
-.. include:: /Includes.rst.txt
-
-=====
-Index
-=====
-
-.. Sphinx will insert here the general index automatically.

Documentation/guides.xml

@@ -0,0 +1,23 @@
+<?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/tea"
+        project-contact="mailto:typo3-coding@oliverklee.de"
+        project-repository="https://github.com/FriendsOfTYPO3/tea"
+        project-issues="https://github.com/FriendsOfTYPO3/tea/issues"
+        edit-on-github-branch="main"
+        edit-on-github="FriendsOfTYPO3/tea"
+        typo3-core-preferred="stable"
+    />
+    <project
+        title="TYPO3 EXT:tea"
+        release="3.1.0"
+        version="3.1"
+        copyright="since 2013 by the TYPO3 contributors"
+    />
+</guides>

composer.json

@@ -164,14 +164,7 @@
 		"ci:xliff:lint": "php Build/bin/console lint:xliff Resources/Private/Language",
 		"ci:yaml:lint": "find . ! -path '*.Build/*' ! -path '*node_modules/*' -regextype egrep -regex '.*.ya?ml$' | xargs -r php ./.Build/bin/yaml-lint",
 		"coverage:create-directories": "mkdir -p .Build/logs .Build/coverage",
-		"docs:generate": [
+		"docs:generate": "docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation",
-			"@docs:generate:pullimage",
-			"docker run --rm ghcr.io/t3docs/render-documentation show-shell-commands > tempfile.sh; echo 'dockrun_t3rd makehtml' >> tempfile.sh; bash tempfile.sh; rm tempfile.sh"
-		],
-		"docs:generate:pullimage": [
-			"docker pull ghcr.io/t3docs/render-documentation",
-			"docker tag ghcr.io/t3docs/render-documentation t3docs/render-documentation"
-		],
 		"fix:composer:normalize": "@composer normalize --no-check-lock",
 		"fix:php": [
 			"@fix:php:cs",