From ad396120aeb9c0ff8ef8174e7267e7814bdf3888 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Wed, 4 Dec 2024 18:56:23 +0100 Subject: [PATCH] [TASK] Migrate docs to PHP-based rendering The Documentation Team introduced the PHP-based rendering (guides) as replacement for the previously used Sphinx-based rendering (which is now deprecated). This change migrates the configuration from Settings.cfg to guides.xml. To generate the docs, a Composer script is introduced: composer docs:generate Additionally, a new GitHub Workflow has been added which checks, if there are warnings or errors on rendering of the documentation. See: https://typo3.org/article/transition-to-full-php-based-rendering-for-all-typo3-extension-manuals --- .github/workflows/docs.yml | 23 +++++++++++++ Documentation/Includes.rst.txt | 36 +------------------ Documentation/Settings.cfg | 63 ---------------------------------- Documentation/guides.xml | 21 ++++++++++++ composer.json | 1 + 5 files changed, 46 insertions(+), 98 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 Documentation/Settings.cfg create mode 100644 Documentation/guides.xml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..003b3f702 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,23 @@ +name: Documentation + +on: + push: + paths: + - 'Documentation/**' + pull_request: + paths: + - 'Documentation/**' + + +jobs: + tests: + name: Rendering + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Documentation renders 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 \ No newline at end of file diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt index ea89f3f5d..b082bae49 100644 --- a/Documentation/Includes.rst.txt +++ b/Documentation/Includes.rst.txt @@ -1,35 +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:: css(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 PHP syntax highlighting - -.. highlight:: php \ No newline at end of file +.. You can put central messages to display on all pages here diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg deleted file mode 100644 index ddb61148b..000000000 --- a/Documentation/Settings.cfg +++ /dev/null @@ -1,63 +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 = ke_search -version = 4.4 -release = 4.4.1 -copyright = since 2011 by ke_search Dev Team - -[html_theme_options] - -# "Edit on GitHub" button -github_branch = master -github_repository = tpwd/ke_search - -# Footer links -project_home = -project_contact = -project_repository = https://github.com/tpwd/ke_search -project_issues = https://github.com/tpwd/ke_search/issues -project_discussions = - -[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/ -# 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_impexp = https://docs.typo3.org/c/typo3/cms-impexp/main/en-us/ -# ext_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/main/en-us/ -# ext_linkvalidator = https://docs.typo3.org/c/typo3/cms-linkvalidator/main/en-us/ -# ext_lowlevel = https://docs.typo3.org/c/typo3/cms-lowlevel/main/en-us/ -# ext_recycler = https://docs.typo3.org/c/typo3/cms-recycler/main/en-us/ -# ext_redirects = https://docs.typo3.org/c/typo3/cms-redirects/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/ \ No newline at end of file diff --git a/Documentation/guides.xml b/Documentation/guides.xml new file mode 100644 index 000000000..c1762b95e --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,21 @@ + + + + + diff --git a/composer.json b/composer.json index 5956f74ae..ebe2cd416 100644 --- a/composer.json +++ b/composer.json @@ -65,6 +65,7 @@ "vendor-dir": ".Build/vendor" }, "scripts": { + "docs:generate": "docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation", "test:unit": ".Build/bin/phpunit -c Tests/phpunit.xml.dist", "test:phpstan": ".Build/bin/phpstan clear-result-cache && .Build/bin/phpstan --configuration=Tests/phpstan.neon > phpstan-report.log", "test:php-cs-fixer": ".Build/bin/php-cs-fixer fix -v --dry-run --using-cache=no > php-cs-fixer-report.log"