From 9b4c0a8f500fa6a033de9704d7c731f05f70b51d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Tue, 7 May 2024 12:18:26 +0200 Subject: [PATCH] [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 | 10 ++++++ Build/Scripts/runTests.sh | 20 ++--------- Documentation/Documentation.rst | 2 +- Documentation/Includes.rst.txt | 35 +------------------ Documentation/Index.rst | 1 - Documentation/Settings.cfg | 62 --------------------------------- Documentation/genindex.rst | 7 ---- Documentation/guides.xml | 23 ++++++++++++ composer.json | 9 +---- 9 files changed, 39 insertions(+), 130 deletions(-) delete mode 100644 Documentation/Settings.cfg delete mode 100644 Documentation/genindex.rst create mode 100644 Documentation/guides.xml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d5c4403..1244e29 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/Build/Scripts/runTests.sh b/Build/Scripts/runTests.sh index 3b1fb29..9fbd670 100755 --- a/Build/Scripts/runTests.sh +++ b/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 - if [ "${CONTAINER_BIN}" == "podman" ]; then - 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 + ${CONTAINER_BIN} run --rm --pull always -v "$(pwd)":/project -it ${IMAGE_DOCS} --config=Documentation --fail-on-log + SUITE_EXIT_CODE=$? ;; functional) [ -z "${TEST_FILE}" ] && TEST_FILE="Tests/Functional" diff --git a/Documentation/Documentation.rst b/Documentation/Documentation.rst index 793e82f..9b996e7 100644 --- a/Documentation/Documentation.rst +++ b/Documentation/Documentation.rst @@ -19,4 +19,4 @@ automatically. .. seealso:: - For further details read the :doc:`TYPO3 Documentation Rendering Guide `. + For further details read the :ref:`TYPO3 Documentation Rendering Guide `. diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt index 1f85da4..8672e23 100644 --- a/Documentation/Includes.rst.txt +++ b/Documentation/Includes.rst.txt @@ -1,34 +1 @@ -.. More information about this file: - 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 +.. You can put central messages to display on all pages here diff --git a/Documentation/Index.rst b/Documentation/Index.rst index b0af62f..1331485 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -58,4 +58,3 @@ continuous integration. :hidden: Sitemap - genindex diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg deleted file mode 100644 index 5d3496e..0000000 --- a/Documentation/Settings.cfg +++ /dev/null @@ -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/ diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst deleted file mode 100644 index 806ec56..0000000 --- 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 0000000..edaec93 --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,23 @@ + + + + + diff --git a/composer.json b/composer.json index 03784c1..a1f464f 100644 --- a/composer.json +++ b/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: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" - ], + "docs:generate": "docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation", "fix:composer:normalize": "@composer normalize --no-check-lock", "fix:php": [ "@fix:php:cs",