[DOCS] Switch to PHP based documentation rendering

* Create guides.xml * Resolve rendering warnings, convert included .rst files into .rst.txt as all .rst files are handled as documents * Remove now outdated Settings.cfg * Remove outdated genindex.rst * Introduce automatic testing for documentation changes * Introduce make file for easy local rendering
FriendsOfTYPO3 · Mar 9, 2024 · 8d66201 · 8d66201
1 parent 28ec5a0
commit 8d66201
Show file tree

Hide file tree

Showing 16 changed files with 74 additions and 81 deletions.
diff --git a/.github/workflows/test-documentation.yml b/.github/workflows/test-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/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 YAML syntax highlighting
-
-.. highlight:: yaml
+..  You can put central messages to display on all pages here
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -133,4 +133,3 @@ use content types as sub-resources inside extensions.
     :hidden:
 
     Sitemap
-    genindex
diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg
diff --git a/...tion/Snippets/AllowedCustomProperties.rst → .../Snippets/AllowedCustomProperties.rst.txt b/...tion/Snippets/AllowedCustomProperties.rst → .../Snippets/AllowedCustomProperties.rst.txt
@@ -1,5 +1,3 @@
-.. include:: /Includes.rst.txt
-
 .. confval:: allowedCustomProperties
 
    :Required: false

diff --git a/Documentation/Snippets/LabelField.rst → Documentation/Snippets/LabelField.rst.txt b/Documentation/Snippets/LabelField.rst → Documentation/Snippets/LabelField.rst.txt
@@ -1,5 +1,3 @@
-.. include:: /Includes.rst.txt
-
 .. confval:: labelField
 
    :Required: true

diff --git a/Documentation/YamlReference/ContentTypes/RecordTypes/Index.rst b/Documentation/YamlReference/ContentTypes/RecordTypes/Index.rst
@@ -45,7 +45,7 @@ Here you can find all :ref:`common root options <yaml_reference_common>`.
 
        table: tx_vendor_my_custom_table_name
 
-.. include:: /Snippets/LabelField.rst
+.. include:: /Snippets/LabelField.rst.txt
 
 .. confval:: typeField
 

diff --git a/Documentation/YamlReference/FieldTypes/Checkbox/Index.rst b/Documentation/YamlReference/FieldTypes/Checkbox/Index.rst
@@ -65,7 +65,7 @@ Settings
    *  :yaml:`checkboxToggle`
    *  :yaml:`checkboxLabeledToggle`
 
-.. include:: /Snippets/AllowedCustomProperties.rst
+.. include:: /Snippets/AllowedCustomProperties.rst.txt
 
 For advanced configuration refer to the :ref:`TCA documentation <t3tca:columns-check>`.
 

diff --git a/Documentation/YamlReference/FieldTypes/Collection/Index.rst b/Documentation/YamlReference/FieldTypes/Collection/Index.rst
@@ -32,7 +32,7 @@ or gif files. These should be 64x64px.
 Settings
 ========
 
-.. include:: /Snippets/LabelField.rst
+.. include:: /Snippets/LabelField.rst.txt
 
 .. confval:: table
 

diff --git a/Documentation/YamlReference/FieldTypes/File/Index.rst b/Documentation/YamlReference/FieldTypes/File/Index.rst
@@ -60,7 +60,7 @@ Settings
 
    It is possible to define crop variants for this specific field and Content
    Block. This documentation only covers the most basic configuration. Refer to
-   the :ref:`TCA documentation <columns-imageManipulation-properties-cropVariants>`
+   the :ref:`TCA documentation <t3tca:columns-imageManipulation-properties-cropVariants>`
    for a complete overview of possibilities.
 
    Example configuration below. The aspect ratios can be defined as a float

diff --git a/Documentation/YamlReference/FieldTypes/Radio/Index.rst b/Documentation/YamlReference/FieldTypes/Radio/Index.rst
@@ -63,7 +63,7 @@ Settings
             </trans-unit>
         </body>
 
-.. include:: /Snippets/AllowedCustomProperties.rst
+.. include:: /Snippets/AllowedCustomProperties.rst.txt
 
 For more advanced configuration refer to the :ref:`TCA documentation <t3tca:columns-radio>`.
 

diff --git a/Documentation/YamlReference/FieldTypes/Select/Index.rst b/Documentation/YamlReference/FieldTypes/Select/Index.rst
@@ -99,7 +99,7 @@ Settings
    prevents the record from being saved if the limit is not satisfied.
    The field can be set as required by setting `minitems` to at least 1.
 
-.. include:: /Snippets/AllowedCustomProperties.rst
+.. include:: /Snippets/AllowedCustomProperties.rst.txt
 
 For more advanced configuration refer to the :ref:`TCA documentation <t3tca:columns-select>`.
 

diff --git a/Documentation/genindex.rst b/Documentation/genindex.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://typo3.org/community/teams/typo3-development/initiatives/structured-content/content-blocks"
+               project-contact="https://typo3.org/community/teams/typo3-development/initiatives/structured-content/"
+               project-repository="https://github.com/nhovratov/content-blocks"
+               project-issues="https://github.com/nhovratov/content-blocks/issues"
+               edit-on-github-branch="main"
+               edit-on-github="nhovratov/content-blocks"
+               typo3-core-preferred="main"
+               interlink-shortcode="contentblocks/content-blocks"
+    />
+    <project title="Content Blocks"
+             release="0.6"
+             copyright="since 2023 by TYPO3 contributors"
+    />
+</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 documentation (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
diff --git a/README.md b/README.md
@@ -78,6 +78,21 @@ Build/Scripts/runTests.sh -s functional
 
 Be sure to exclude the `.Build/public/typo3temp` directory from indexing in your IDE (e.g. PhpStorm) before starting the tests.
 
+## Rendering the documentation
+
+When you update the documentation you can try out rendering it locally
+(Docker required):
+
+```
+make docs
+```
+
+You can test if the syntax and references are ok with
+
+```
+make test-docs
+```
+
 ## Feedback
 
 You can reach us on the TYPO3 Slack channel `#cig-structuredcontent`. We
Original file line number	Diff line number	Diff line change
Expand Up		@@ -133,4 +133,3 @@ use content types as sub-resources inside extensions.
		:hidden:

		Sitemap
		genindex