[DOCS] Switch to PHP-based rendering (#623)

* [DOCS] Switch to PHP-based rendering - Fix references where the old rendering was more forgiven then the new one - Fix references that do currently not work - Explicitly link to TYPO3 v11.5 where TCA settings were removed, use the current stable TYPO3 version for links otherwise - Introduce automatic tests for documentation You can locally render the documentation with: ``` make docs ``` * [DOCS] Adjust field config documentation --------- Co-authored-by: Nikita Hovratov <[email protected]> (cherry picked from commit 9db8bea)
Gernott · Mar 2, 2024 · a3edd43 · a3edd43
1 parent d8fafa9
commit a3edd43
Show file tree

Hide file tree

Showing 18 changed files with 69 additions and 65 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,17 @@
+name: test documentation
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    name: documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Test if the documentation will render without warnings
+        run: |
+          mkdir -p Documentation-GENERATED-temp \
+          && 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/Documentation/ChangeLog/7.2/Index.rst b/Documentation/ChangeLog/7.2/Index.rst
@@ -277,11 +277,11 @@ Mask is now deprecation free in TYPO3 v11 in terms of TCA migrations. The
 following migrations are done by Mask to mitigate deprecation log entries from
 the core:
 
-*  The new option :ref:`showNewRecordLink <t3tca:columns-inline-properties-showNewRecordLink>`
+*  The new option :ref:`showNewRecordLink <t3tca:columns-inline-properties-appearance>`
    has been added, while the former `levelLinksPosition` option with the value
    `none` is migrated to use this option.
 
-*  The new option :ref:`fileFolderConfig <columns-select-properties-fileFolderConfig>`
+*  The new option :ref:`fileFolderConfig <t3tca:columns-select-properties-fileFolderConfig>`
    is now used instead of the old separate versions.
 
 Bugfixes

diff --git a/Documentation/Fieldtypes/Type/Content.rst b/Documentation/Fieldtypes/Type/Content.rst
@@ -34,7 +34,7 @@ Available TCA options
 *  :ref:`config.maxitems <t3tca:tca_property_maxitems>`
 *  :ref:`config.appearance.newRecordLinkTitle <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.levelLinksPosition <t3tca:columns-inline-properties-appearance>`
-*  :ref:`config.appearance.showNewRecordLink <columns-inline-properties-showNewRecordLink>` (only v11 or higher)
+*  :ref:`config.appearance.showNewRecordLink <t3tca:columns-inline-properties-appearance>` (only v11 or higher)
 *  :ref:`config.appearance.collapseAll <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.expandSingle <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.useSortable <t3tca:columns-inline-properties-appearance>`

diff --git a/Documentation/Fieldtypes/Type/File.rst b/Documentation/Fieldtypes/Type/File.rst
@@ -28,10 +28,10 @@ File field using :ref:`FAL<t3coreapi:using-fal>`.
 Available TCA options
 ---------------------
 
-*  :ref:`imageoverlayPalette <columns-inline-examples-fal>` (custom Mask option, which enables the core TCA palette `imageoverlayPalette` used for images)
+*  :ref:`imageoverlayPalette <t3tca-11:columns-inline-examples-fal>` (custom Mask option, which enables the core TCA palette `imageoverlayPalette` used for images)
 *  :ref:`config.minitems <t3tca:tca_property_minitems>`
 *  :ref:`config.maxitems <t3tca:tca_property_maxitems>`
-*  :ref:`allowedFileExtensions <t3tca:columns-group-properties-appearance>` (used in :ref:`overrideChildTca <columns-inline-properties-overrideChildTca>`)
+*  :ref:`allowedFileExtensions <t3tca:columns-group-properties-appearance>` (used in :ref:`overrideChildTca <t3tca:columns-inline-properties-overrideChildTca>`)
 *  :ref:`config.appearance.collapseAll <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.expandSingle <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.useSortable <t3tca:columns-inline-properties-appearance>`

diff --git a/Documentation/Fieldtypes/Type/Float.rst b/Documentation/Fieldtypes/Type/Float.rst
@@ -33,8 +33,8 @@ Available TCA options
 *  :ref:`config.size <t3tca:columns-input-properties-size>`
 *  :ref:`config.eval.required <t3tca:columns-input-properties-eval>`
 *  :ref:`config.max <t3tca:columns-input-properties-max>`
-*  :ref:`config.range.lower <t3tca:columns-input-properties-range>`
-*  :ref:`config.range.upper <t3tca:columns-input-properties-range>`
+*  :ref:`config.range.lower <t3tca:columns-number-properties-range>`
+*  :ref:`config.range.upper <t3tca:columns-number-properties-range>`
 *  :ref:`config.slider.step <t3tca:columns-input-properties-slider>`
 *  :ref:`config.slider.width <t3tca:columns-input-properties-slider>`
 *  :ref:`l10n_mode <t3tca:columns-properties-l10n-mode>`

diff --git a/Documentation/Fieldtypes/Type/Inline.rst b/Documentation/Fieldtypes/Type/Inline.rst
@@ -34,7 +34,7 @@ Available TCA options
 *  :ref:`config.maxitems <t3tca:tca_property_maxitems>`
 *  :ref:`config.appearance.newRecordLinkTitle <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.levelLinksPosition <t3tca:columns-inline-properties-appearance>`
-*  :ref:`config.appearance.showNewRecordLink <columns-inline-properties-showNewRecordLink>` (only v11 or higher)
+*  :ref:`config.appearance.showNewRecordLink <t3tca:columns-inline-properties-appearance>` (only v11 or higher)
 *  :ref:`config.appearance.collapseAll <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.expandSingle <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.useSortable <t3tca:columns-inline-properties-appearance>`

diff --git a/Documentation/Fieldtypes/Type/Integer.rst b/Documentation/Fieldtypes/Type/Integer.rst
@@ -33,8 +33,8 @@ Available TCA options
 *  :ref:`config.size <t3tca:columns-input-properties-size>`
 *  :ref:`config.eval.required <t3tca:columns-input-properties-eval>`
 *  :ref:`config.max <t3tca:columns-input-properties-max>`
-*  :ref:`config.range.lower <t3tca:columns-input-properties-range>`
-*  :ref:`config.range.upper <t3tca:columns-input-properties-range>`
+*  :ref:`config.range.lower <t3tca:columns-number-properties-range>`
+*  :ref:`config.range.upper <t3tca:columns-number-properties-range>`
 *  :ref:`config.slider.step <t3tca:columns-input-properties-slider>`
 *  :ref:`config.slider.width <t3tca:columns-input-properties-slider>`
 *  :ref:`l10n_mode <t3tca:columns-properties-l10n-mode>`

diff --git a/Documentation/Fieldtypes/Type/Link.rst b/Documentation/Fieldtypes/Type/Link.rst
@@ -31,8 +31,8 @@ Available TCA options
 *  :ref:`config.placeholder <t3tca:tca_property_placeholder>`
 *  :ref:`config.size <t3tca:columns-input-properties-size>`
 *  :ref:`config.eval.required <t3tca:columns-input-properties-eval>`
-*  :ref:`config.fieldControl.linkPopup.options.allowedExtensions <t3tca:tca_property_fieldControl_linkPopup>`
-*  :ref:`config.fieldControl.linkPopup.options.blindLinkOptions <t3tca:tca_property_fieldControl_linkPopup>`
+*  :ref:`config.fieldControl.linkPopup.options.allowedExtensions <t3tca:columns-link-properties-appearance>`
+*  :ref:`config.fieldControl.linkPopup.options.blindLinkOptions <t3tca:columns-link-properties-appearance>`
 *  :ref:`l10n_mode <t3tca:columns-properties-l10n-mode>`
 *  :ref:`config.behaviour.allowLanguageSynchronization <t3tca:tca_property_behaviour_allowLanguageSynchronization>`
 *  :ref:`config.eval.null <t3tca:columns-input-properties-eval>`

diff --git a/Documentation/Fieldtypes/Type/Media.rst b/Documentation/Fieldtypes/Type/Media.rst
@@ -42,7 +42,7 @@ Available TCA options
 *  `onlineMedia` (custom Mask option, which toggles available online media types)
 *  :ref:`config.minitems <t3tca:tca_property_minitems>`
 *  :ref:`config.maxitems <t3tca:tca_property_maxitems>`
-*  :ref:`allowedFileExtensions <t3tca:columns-group-properties-appearance>` (used in :ref:`overrideChildTca <columns-inline-properties-overrideChildTca>`)
+*  :ref:`allowedFileExtensions <t3tca:columns-group-properties-appearance>` (used in :ref:`overrideChildTca <t3tca:columns-inline-properties-overrideChildTca>`)
 *  :ref:`config.appearance.collapseAll <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.expandSingle <t3tca:columns-inline-properties-appearance>`
 *  :ref:`config.appearance.useSortable <t3tca:columns-inline-properties-appearance>`

diff --git a/Documentation/Fieldtypes/Type/Timestamp.rst b/Documentation/Fieldtypes/Type/Timestamp.rst
@@ -28,7 +28,7 @@ An input field for a date (stored as UNIX timestamp).
 Available TCA options
 ---------------------
 
-*  :ref:`config.eval <columns-input-renderType-inputDateTime-eval>`
+*  :ref:`config.eval <t3tca-11:columns-input-renderType-inputDateTime-eval>`
 *  :ref:`config.default <t3tca:tca_property_default>`
 *  :ref:`config.placeholder <t3tca:tca_property_placeholder>`
 *  :ref:`config.range.lower <t3tca:columns-input-datetime-properties-range>`

diff --git a/Documentation/Glossary/Index.rst b/Documentation/Glossary/Index.rst
@@ -13,7 +13,7 @@ Here you can find explanations for common terms when working with Mask.
 Fluid Styled Content
 ====================
 
-:ref:`Fluid Styled Content<t3fsc:start>` is a core extension of TYPO3 which provides all the regular content elements
+:doc:`Fluid Styled Content<typo3/cms-fluid-styled-content:Index>` is a core extension of TYPO3 which provides all the regular content elements
 you can find in your installation like Header, Text and Text & Images. Mask does not depend on it directly, but it is
 good practice to include it nevertheless. Most of the time you will want to have some generic content elements for your
 site. Even if you don't need them, this extension includes the TypoScript snippet `lib.parseFunc_RTE` too, which is

diff --git a/Documentation/Guides/RTEConfig.rst b/Documentation/Guides/RTEConfig.rst
@@ -6,7 +6,7 @@
 RTE Config
 ==========
 
-You can exactly define which :ref:`RTE config <cms-rte-ckeditor:config-examples>` a mask element should offer for its
+You can exactly define which :ref:`RTE config <typo3/cms-rte-ckeditor:config-examples>` a mask element should offer for its
 richtext fields.
 
 For this, you have to follow these 3 steps:

diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt
@@ -1,14 +1 @@
-.. This is 'Includes.txt'. It is included at the very top of each and
-   every ReST source file in this documentation project (= manual).
-
-.. role:: typoscript(code)
-.. role:: html(code)
-.. role:: ts(typoscript)
-   :class: typoscript
-
-.. role:: php(code)
-.. role:: sql(code)
-.. role:: shell(code)
-
-.. default-role:: code
-.. highlight:: php
+..  You can put central messages to display on all pages here
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -71,4 +71,3 @@ Mask
    ChangeLog/Index
    Sponsors/Index
    ToDoList/Index
-   Targets
diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg
diff --git a/Documentation/Targets.rst b/Documentation/Targets.rst
diff --git a/Documentation/guides.xml b/Documentation/guides.xml
@@ -0,0 +1,19 @@
+<?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/mask"
+               project-contact="https://typo3.slack.com/archives/C0FD5F6P2"
+               project-repository="https://github.com/Gernott/mask"
+               project-issues="https://github.com/Gernott/mask/issues"
+               edit-on-github-branch="main"
+               edit-on-github="Gernott/mask"
+               typo3-core-preferred="stable"
+               interlink-shortcode="mask/mask"
+    />
+    <project title="Mask"
+             release="8.3.9"
+             copyright="2024"
+    />
+</guides>
diff --git a/Makefile b/Makefile
@@ -0,0 +1,16 @@
+.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}'
+
+.PHONY: docs
+docs: ## Generate projects docs (from "Documentation" directory)
+	mkdir -p Documentation-GENERATED-temp
+
+	docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
+
+.PHONY: test-docs
+test-docs: ## Test the documentation rendering
+	mkdir -p Documentation-GENERATED-temp
+
+	docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log