Documentation php rendering

.editorconfig

@@ -74,3 +74,8 @@ indent_size = 4
 [*.sql]
 indent_style = tab
 indent_size = 2
+
+# Makefile
+[{Makefile,**.mk}]
+# Use tabs for indentation (Makefiles require tabs)
+indent_style = tab

.github/workflows/test.yml

@@ -62,3 +62,9 @@ jobs:
 
       - name: Run TypoScript linter
         run: composer run-script test-typoscript-lint
+
+      - name: Render and test documentation
+        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 --minimal-test

Documentation/AdministratorManual/Index.rst

@@ -26,12 +26,14 @@ The output is managed via content modules. This means easy and flexible usage.
 
 .. figure:: ../Images/AdministratorManual/plugin.png
 	:alt: Insert plugin
+   :class: with-shadow
 
 Choose one or more of the plugins listed to build your blog. These can be distributed to different columns.
 
 
 .. figure:: ../Images/Installation/plugin_blogsystem.png
 	:alt: Modules
+   :class: with-shadow
 
 
 Plugins
@@ -44,6 +46,7 @@ Main plugin of the extension. Provides post list and detail view. Enables users
 
 .. figure:: ../Images/AdministratorManual/blogsystem.png
 	:alt: Blogsystem
+   :class: with-shadow
 
 
 Archive
@@ -53,6 +56,7 @@ This plugin displays a list of your blog posts, nested by month and sorted by da
 
 .. figure:: ../Images/AdministratorManual/archive.png
 	:alt: Archive
+   :class: with-shadow
 
 
 Categories
@@ -89,6 +93,7 @@ Depending on your configuration users can confirm, add and remove subscriptions
 
 .. figure:: ../Images/AdministratorManual/subscription-manager.png
 	:alt: Subscription Manager
+   :class: with-shadow
 
 We've already did some basic settings for this plugin in the installation process, but you should do so some more configuration.
 
@@ -127,12 +132,14 @@ The RSS-Module need some special treatment, but no need to worry. Just create a
 
 .. figure:: ../Images/AdministratorManual/rssincludestatic.png
 	:alt: RSS include static
+   :class: with-shadow
 
 
 When you open the page, the output should look like this:
 
 .. figure:: ../Images/AdministratorManual/rssoutput.png
 	:alt: RSS output
+   :class: with-shadow
 
 Have a look at :code:`/Configuration/TypoScript/RSS/setup.typoscript`
 You can override the values by using an extension template on the page where your have insert the Rss-modul.

Documentation/Configuration/Index.rst

@@ -7,16 +7,15 @@
 
 Target group: **Administrators**
 
-.. contents:: Within this page
-   :local:
-   :depth: 3
-
-
 .. _configuration:
 
 Configuration
 =============
 
+.. contents:: Within this page
+   :local:
+   :depth: 3
+
 
 Minimal configuration
 ---------------------

Documentation/DeveloperGuide/Index.rst

@@ -18,7 +18,6 @@ Target group: **Developers**
    :depth: 3
 
 
-
 Extending T3extlog
 ------------------
 .. _dev-guide-extending:
@@ -121,12 +120,16 @@ Documentation
 Anyone is very welcome to help improving our documentation!
 Just send a pull request or add an issue at GitHub.
 
-To view your changes before submitting them you will need to install following extensions:
+This extension uses the PHP based rendering approach. See here for more info:
+
+* https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Index.html
+* https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/RenderingDocs/Index.html
+* https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/Migration/Index.html
+
 
-* EXT:sphinx
-* EXT:restdoc
+Use this command to render the documentation locally (Docker is needed):
 
-See this link for more information: https://docs.typo3.org/typo3cms/extensions/sphinx/WritersManual/SphinxRest/Index.html
+`docker run --rm --pull always -v "$(pwd):/project" -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation`
 
 
 Testing
@@ -141,17 +144,17 @@ https://extensions.typo3.org/extension/introduction
 **What needs to be tested:**
 
 * Creating blog posts (with and without preview image and text)
-   * Check post preview
+    * Check post preview
 * Posting comments and subscribe for new comments
-	* With and without SPAM check triggered
-	* Test field validation
-   * Test prefilling fields
+    * With and without SPAM check triggered
+    * Test field validation
+    * Test prefilling fields
 * Using the subscription manager (confirm and delete for new comment and post subscription)
 * New comment subscription
-	* Admin, subscriber opt-in and notification emails
-	* Triggered by:
-      * Frontend & backend (confirm and un-spam a comment)
-      * Edit button (BE module and core dashboard) and direct spam / confirmed toggle buttons
+    * Admin, subscriber opt-in and notification emails
+    * Triggered by:
+        * Frontend & backend (confirm and un-spam a comment)
+        * Edit button (BE module and core dashboard) and direct spam / confirmed toggle buttons
 	* Make sure mails are sent with localized links for multi language setups
 * New post subscription
 	* Subscriber opt-in (frontend) and notification emails (button in BE module)

Documentation/Installation/Full.rst

@@ -1,17 +1,20 @@
 .. ==================================================
 .. FOR YOUR INFORMATION
 .. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
+.. --- coding: utf-8 --- with BOM.
 
 .. include:: ../Includes.txt
 
 .. _installation:
 
-
 Installation
 ============
 
-Target group: **Administrators**
+Target group: --Administrators--
+
+.. contents:: Within this page
+   :local:
+   :depth: 3
 
 
 Installation process - step by step
@@ -26,67 +29,76 @@ Some steps are already described in the :ref:`Quick Installation <quick_installa
 
 
 #. Import and install the extension
-	- via the extension manager
-	- or using composer
+
+   - via the extension manager
+   - or using composer
 
 #. Create the following pages
-	- See :ref:`Quick Installation <quick_installation>`
-	- Optional: add an RSS page (standard page) which will contain the RSS plugin
-	- Optional: add a page (standard page) for subscribing to new blog posts
 
-	.. figure:: ../Images/Installation/pagestructure.png
-		:alt: Recommended page structure
+   - See :ref:`Quick Installation <quick_installation>`
+   - Optional: add an RSS page (standard page) which will contain the RSS plugin
+   - Optional: add a page (standard page) for subscribing to new blog posts
+
+   .. figure:: ../Images/Installation/pagestructure.png
+      :alt: Recommended page structure
+      :class: with-shadow
 
 #. Include static TypoScript template
-	This can be done on your root-page or in an extension template for a specific page.
-	Minimum requirement: `T3Extblog: Default Setup (needed)`.
-	Do NOT include `T3Extblog: RSS setup`! We will need this elsewhere.
 
-	.. figure:: ../Images/Installation/includestatic.png
-		:alt: Include static
+   This can be done on your root-page or in an extension template for a specific page.
+
+   Minimum requirement: `T3Extblog: Default Setup (needed)`.
+   Do NOT include `T3Extblog: RSS setup`! We will need this elsewhere.
+
+   .. figure:: ../Images/Installation/includestatic.png
+      :alt: Include static
+      :class: with-shadow
 
 #. Add plugins to the pages
-	- See :ref:`Quick Installation <quick_installation>`
-	- Optional: add the RSS plugin to your RSS page
-	- Optional: add the blog subscription form plugin to the previously created page
+
+   - See :ref:`Quick Installation <quick_installation>`
+   - Optional: add the RSS plugin to your RSS page
+   - Optional: add the blog subscription form plugin to the previously created page
 
 #. Configure settings in the constant editor module:
-	.. figure:: ../Images/Installation/constant_editor.png
-		:alt: Constant editor backend module
 
-Or use TypoScript:
+   .. figure:: ../Images/Installation/constant_editor.png
+      :alt: Constant editor backend module
+      :class: with-shadow
+
+   Or use TypoScript:
 
 #. Start to configure your Blog. This is an TypoScript example:
 
-.. code-block:: typoscript
-	:linenos:
-
-		plugin.tx_t3extblog {
-			settings {
-				blogsystem {
-					posts {
-						paginate {
-							insertAbove = 1
-							maximumNumberOfLinks = 1
-						}
-					}
-					comments {
-						allowedUntil = +5 years
-						approvedByDefault = 1
-						subscribeForComments = 0
-					}
-				}
-			}
-		}
-		module.tx_t3extblog < plugin.tx_t3extblog
-
-See :ref:`Configuration <configuration>` for all possible settings.
+   .. code-block:: typoscript
+      :linenos:
+
+         plugin.tx_t3extblog {
+            settings {
+               blogsystem {
+                  posts {
+                     paginate {
+                        insertAbove = 1
+                        maximumNumberOfLinks = 1
+                     }
+                  }
+                  comments {
+                     allowedUntil = +5 years
+                     approvedByDefault = 1
+                     subscribeForComments = 0
+                  }
+               }
+            }
+         }
+         module.tx_t3extblog < plugin.tx_t3extblog
+
+   See :ref:`Configuration <configuration>` for all possible settings.
 
 
 .. important::
 
-	Assigning the TypoScript settings to backend context by using :code:`module.tx_t3extblog < plugin.tx_t3extblog` is
-   essential when overriding values. Don't forget it!
+	Assigning the TypoScript settings to backend context by using :code:`module.tx_t3extblog < plugin.tx_t3extblog` is essential
+	when overriding values. Don't forget it!
 
 .. important::
 
@@ -97,7 +109,7 @@ See :ref:`Configuration <configuration>` for all possible settings.
 	It is recommended to use the constants in conjunction with custom TypoScript. Copy both configuration files
 	(`constants.typoscript` and `setup.typoscript` located in `EXT:t3extblog/Configuration/TypoScript`) and include
 	(using :code:`<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_extension/.../setup.typoscript">` them in your root template.
-   This is overall more flexible than using the site sets settings approach.
+	This is overall more flexible than using the site sets settings approach.
 
 
 Next Steps

Documentation/Installation/Quick.rst

@@ -8,12 +8,14 @@
 
 .. _quick_installation:
 
-
 Quick Installation
 ==================
 
 Target group: **Integrators**
 
+.. contents:: Within this page
+   :local:
+   :depth: 3
 
 Quick installation guide
 ------------------------
@@ -25,33 +27,42 @@ Quick installation guide
 T3Extblog can be installed quickly by using the site settings. You need to perform the following steps:
 
 #. Import and install the extension
-	- via the extension manager
-	- or using composer
+
+   - via the extension manager
+   - or using composer
 
 #. Include configuration (site set)
+
 	Include the extension site set using the Sites module:
 
 	.. figure:: ../Images/Installation/site-set.png
 		:alt: Include site set
+      :class: with-shadow
 
 #. Create a simple page structure for your blog
+
 	At least we need a page for the actual blog and a page for the subscription manager.
    We recommend to create a sysfolder for your blogposts too.
 
 	.. figure:: ../Images/QuickInstallation/quickinstallation_folderstructur.png
 		:alt: Recommended page structure for quick installation
+      :class: with-shadow
 
 #. Add plugins to the pages:
+
 	On our main blog page we insert the plugin 'Blogsystem'
    (see :ref:`Administration manual <admin-manual>` for the other plugins we can use).
 
 	.. figure:: ../Images/Installation/plugin_blogsystem.png
 		:alt: Insert the "Blogsystem"
+      :class: with-shadow
 
 	On our subscription manager page, we need to add the "Subscription Manager" plugin.
 
 #. Configure settings in the settings module:
+
 	.. figure:: ../Images/Installation/site-set-configuration.png
 		:alt: Extension site set settings
+      :class: with-shadow
 
 See :ref:`Configuration <configuration>` for all possible settings.