[TASK] List common configuration file locations as files

This uses the new rst feature TYPO3-Documentation/render-guides#898

Releases: main, 13.4, 12.4

Documentation/ExtensionArchitecture/FileStructure/Configuration/Backend/Index.rst

@@ -1,60 +1,63 @@
-.. include:: /Includes.rst.txt
-.. index::
-   Extension development; Configuration/Backend
-   Path; EXT:{extkey}/Configuration/Backend
+:navigation-title: Backend
+
+..  include:: /Includes.rst.txt
+..  index::
+    Extension development; Configuration/Backend
+    Path; EXT:{extkey}/Configuration/Backend
 
 .. _extension-configuration-backend:
 
-===============
-:file:`Backend`
-===============
+========================================
+Extension folder `Configuration/Backend`
+========================================
 
 The folder :file:`EXT:my_extension/Configuration/Backend/` may contain
 configuration that is important within the TYPO3 Backend.
 
 All files in this directory are automatically included during the TYPO3
 bootstrap.
 
-.. _extension-configuration-backend-ajaxroutes:
-
-:file:`AjaxRoutes.php`
-======================
-
-Complete path: :file:`EXT:my_extension/Configuration/Backend/AjaxRoutes.php`
-
-In this file routes for Ajax requests that should be used in the backend can
-be defined.
-
-Read more about :ref:`Using Ajax in the backend <ajax-backend>`.
-
-.. include:: /CodeSnippets/Manual/Extension/Configuration/BackendAjaxRoutes.rst.txt
+..  _extension-configuration-backend-ajaxroutes:
 
+..  typo3:file:: AjaxRoutes.php
+    :scope: extension
+    :path: /Configuration/Backend/
+    :regex: /^.*Configuration\/Backend\/AjaxRoutes\.php$/
+    :shortDescription: Defines routes for backend Ajax requests
 
-.. _extension-configuration-backend-routes:
+    In this file routes for Ajax requests that should be used in the backend can
+    be defined.
 
-:file:`Routes.php`
-==================
+    Read more about :ref:`Using Ajax in the backend <ajax-backend>`.
 
-Complete path: :file:`EXT:my_extension/Configuration/Backend/Routes.php`
+..  include:: /CodeSnippets/Manual/Extension/Configuration/BackendAjaxRoutes.rst.txt
 
-This file maps from paths used in the backend to the controller that should
-be used.
+..  _extension-configuration-backend-routes:
 
-Most backend routes defined in the TYPO3 core can be found in the following
-file, which you can use as example:
+..  typo3:file:: Routes.php
+    :scope: extension
+    :path: /Configuration/Backend/
+    :regex: /^.*Configuration\/Backend\/Routes\.php$/
+    :shortDescription: Defines routes for backend controllers
 
-:t3src:`backend/Configuration/Backend/Routes.php`
+    This file maps from paths used in the backend to the controller that should
+    be used.
 
-Read more about :ref:`Backend routing <backend-routing>`.
+    Most backend routes defined in the TYPO3 core can be found in the following
+    file, which you can use as example:
 
+    :t3src:`backend/Configuration/Backend/Routes.php`
 
-.. _extension-configuration-backend-modules:
+    Read more about :ref:`Backend routing <backend-routing>`.
 
-:file:`Modules.php`
-====================
+..  _extension-configuration-backend-modules:
 
-Complete path: :file:`EXT:my_extension/Configuration/Backend/Modules.php`.
+..  typo3:file:: Modules.php
+    :scope: extension
+    :path: /Configuration/Backend/
+    :regex: /^.*Configuration\/Backend\/Modules\.php$/
+    :shortDescription: Defines the backend module configuration
 
-This file is used for the
-:ref:`Backend module configuration <backend-modules-configuration>`. See that
-chapter for details.
+    This file is used for the
+    :ref:`Backend module configuration <backend-modules-configuration>`. See that
+    chapter for details.

Documentation/ExtensionArchitecture/FileStructure/Configuration/ContentSecurityPolicies.rst

@@ -8,10 +8,16 @@
 :file:`ContentSecurityPolicies.php`
 ===================================
 
-.. versionadded:: 12.3
+..  typo3:file:: ContentSecurityPolicies.php
+    :scope: extension
+    :path: /Configuration/
+    :regex: /^.*Configuration\/ContentSecurityPolicies\.php$/
+    :shortDescription: Provides Content Security Policies for frontend and backend.
 
-This file provides :ref:`Content Security Policies <content-security-policy>`
-for frontend and backend.
+    .. versionadded:: 12.3
 
-For details see the chapter about
-:ref:`Extension-specific Content Security Policy <content-security-policy-extension>`.
+    This file provides :ref:`Content Security Policies <content-security-policy>`
+    for frontend and backend.
+
+    For details see the chapter about
+    :ref:`Extension-specific Content Security Policy <content-security-policy-extension>`.

Documentation/ExtensionArchitecture/FileStructure/Configuration/Extbase/Index.rst

@@ -2,9 +2,9 @@
 .. _extension-configuration-extbase:
 .. index:: Path; EXT:{extkey}/Configuration/Extbase
 
-================================
-:file:`Extbase`
-================================
+=========
+`Extbase`
+=========
 
 This configuration folder can contain the following subfolders:
 

Documentation/ExtensionArchitecture/FileStructure/Configuration/Extbase/Persistence/Index.rst

@@ -10,12 +10,15 @@ This folder can contain the following files:
 
 ..  _extension-configuration-extbase-persistence-classes:
 
-:file:`Classes.php`
-===================
+..  typo3:file:: Classes.php
+    :scope: extension
+    :path: /Configuration/Extbase/Persistence/Classes.php
+    :regex: /^.*Configuration\/Extbase\/Persistence\/Classes\.php$/
+    :shortDescription: Contains the mapping between a database table and its Extbase model
 
-In the file :file:`EXT:my_extension/Configuration/Extbase/Persistence/Classes.php` the
-mapping between a database table and its model can be configured. The mapping
-in this file overrides the automatic mapping by naming convention.
+    In the file :file:`EXT:my_extension/Configuration/Extbase/Persistence/Classes.php` the
+    mapping between a database table and its model can be configured. The mapping
+    in this file overrides the automatic mapping by naming convention.
 
-..  seealso::
-    :ref:`Connecting the model to the database <extbase-Persistence>`
+    ..  seealso::
+        :ref:`Connecting the model to the database <extbase-Persistence>`

Documentation/ExtensionArchitecture/FileStructure/Configuration/Icons.rst

@@ -8,10 +8,16 @@
 :file:`Icons.php`
 =================
 
-In this file custom icons can be registered in the
-:php:`\TYPO3\CMS\Core\Imaging\IconRegistry`.
+..  typo3:file:: Icons.php
+    :scope: extension
+    :path: /Configuration/
+    :regex: /^.*Configuration\/Icons\.php$/
+    :shortDescription: Registration of custom icons
 
-See the :ref:`Icon API <icon>` for details.
+    In this file custom icons can be registered in the
+    :php:`\TYPO3\CMS\Core\Imaging\IconRegistry`.
+
+    See the :ref:`Icon API <icon>` for details.
 
 ..  literalinclude:: /ApiOverview/Icon/_Icons.php
     :language: php

Documentation/ExtensionArchitecture/FileStructure/Configuration/Index.rst

@@ -1,13 +1,15 @@
+:navigation-title: Configuration
+
 ..  include:: /Includes.rst.txt
 ..  index::
     Extension development; File name conventions
     Path; EXT:{extkey}/Configuration
 ..  _extension-files-configuration:
 ..  _extension-configuration-files:
 
-======================
-:file:`Configuration`
-======================
+================================
+Extension folder `Configuration`
+================================
 
 The folder :file:`EXT:my_extension/Configuration/` may contain
 configuration of different types.

Documentation/ExtensionArchitecture/FileStructure/Configuration/PageTsconfig.rst

@@ -14,11 +14,17 @@
 
     Only put page TSconfig in this file which absolutely has to be set globally.
 
-In this file global page TSconfig can be stored. It will be automatically
-included for all pages.
+..  typo3:file:: page.tsconfig
+    :scope: extension
+    :path: /Configuration/
+    :regex: /^.*Configuration\/page\.tsconfig$/
+    :shortDescription: Global page TSconfig
 
-For details see
-:ref:`Setting the page TSconfig globally <t3tsref:pagesettingdefaultpagetsconfig>`.
+    In this file global page TSconfig can be stored. It will be automatically
+    included for all pages.
+
+    For details see
+    :ref:`Setting the page TSconfig globally <t3tsref:pagesettingdefaultpagetsconfig>`.
 
 .. code-block:: typoscript
    :caption: EXT:some_extension/Configuration/page.tsconfig

Documentation/ExtensionArchitecture/FileStructure/Configuration/RequestMiddlewaresPhp.rst

@@ -9,13 +9,17 @@
 :file:`RequestMiddlewares.php`
 ================================
 
-Full path to this file is: :file:`Configuration/RequestMiddlewares.php`.
+..  typo3:file:: RequestMiddlewares.php
+    :scope: extension
+    :path: /Configuration/
+    :regex: /^.*Configuration\/RequestMiddlewares\.php$/
+    :shortDescription: Configuration of user-defined middlewares for frontend and backend
 
-Configuration of user-defined middlewares for frontend and backend. Extensions
-that add middlewares or disable existing middlewares configure them in this
-file. The file must return an array with the configuration.
+    Configuration of user-defined middlewares for frontend and backend. Extensions
+    that add middlewares or disable existing middlewares configure them in this
+    file. The file must return an array with the configuration.
 
-See :ref:`Configuring middlewares <request-handling-configuring-middlewares>`
-for details.
+    See :ref:`Configuring middlewares <request-handling-configuring-middlewares>`
+    for details.
 
 .. include:: /CodeSnippets/Manual/Extension/Configuration/RequestMiddlewares.rst.txt

Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst

@@ -4,9 +4,23 @@
    Path; EXT:{extkey}/Configuration/Services.yaml
 .. _extension-configuration-services-yaml:
 
-================================
-:file:`Services.yaml`
-================================
+===============
+`Services.yaml`
+===============
+
+It is possible to use a YAML or PHP format:
+
+..  typo3:file:: Services.yaml
+    :scope: extension
+    :path: /Configuration/
+    :regex: /^.*Configuration\/Services\.yaml$/
+    :shortDescription: Dependency injection service configuration
+
+..  typo3:file:: Services.php
+    :scope: extension
+    :path: /Configuration/
+    :regex: /^.*Configuration\/Services\.php$/
+    :shortDescription: Dependency injection service configuration
 
 Services can be configured in this file. TYPO3 uses it for:
 

Documentation/ExtensionArchitecture/FileStructure/Configuration/TCA/Index.rst

@@ -1,12 +1,14 @@
+:navigation-title: TCA
+
 ..  include:: /Includes.rst.txt
 ..  index::
     Extension development; Configuration/TCA
     Path; EXT:{extkey}/Configuration/TCA
 ..  _extension-configuration-tca:
 
-===========
-:file:`TCA`
-===========
+====================================
+Extension folder `Configuration/TCA`
+====================================
 
 The folder :file:`EXT:my_extension/Configuration/TCA/` may contain or override
 :ref:`TCA (TYPO3 configuration array) <t3tca:introduction>` data.
@@ -24,21 +26,36 @@ All files in this directory are automatically included during the TYPO3
         with the risk of a leakage to the following files. The use of :php:`call_user_func()`
         wrap was a common workaround.
 
-:file:`<tablename>.php`
-=======================
+..  _extension-configuration-tca-table:
+
+`Configuration/TCA/<tablename>.php`
+===================================
 
-One file per database table, using the name of the table for the file, plus
-".php". Only for new tables.
+..  typo3:file:: <tablename>.php
+    :name: configuration-tca
+    :scope: extension
+    :path: /Configuration/TCA
+    :regex: /^.*Configuration\/TCA\/.*\.php$/
+    :shortDescription: Contains the TCA (TYPO3 configuration array), which initially defines the table <tablename>. Change existing tables in directory TCA/Overrides
 
+    One file per database table, using the name of the table for the file, plus
+    ".php". Only for new tables.
 
 ..  index:: Path; EXT:{extkey}/Configuration/TCA/Overrides
 ..  _extension-configuration-tca-overrides:
 
-:file:`Overrides`
-=================
+`Configuration/TCA/Overrides/somefile.php`
+==========================================
+
+..  typo3:file:: somefile.php
+    :name: configuration-tca-overrides
+    :scope: extension
+    :path: /Configuration/TCA/Overrides
+    :regex: /^.*Configuration\/TCA\/Overrides\/.*\.php$/
+    :shortDescription: Extends the TCA (TYPO3 configuration array) of a table
 
-For extending existing tables.
+    For extending existing tables.
 
-General advice: One file per database table, using the name of the table for the
-file, plus :file:`.php`. For more information, see the chapter
-:ref:`Extending the TCA array <storing-changes-extension>`.
+    General advice: One file per database table, using the name of the table for the
+    file, plus :file:`.php`. For more information, see the chapter
+    :ref:`Extending the TCA array <storing-changes-extension>`.

Documentation/ExtensionArchitecture/FileStructure/Configuration/TsConfig/Index.rst

@@ -14,12 +14,22 @@
     Default user TSconfig can be provided in file
     :ref:`extension-configuration-user_tsconfig`.
 
-Configuration/TsConfig/Page
+..  typo3:file:: something.tsconfig
+    :scope: extension
+    :path: /Configuration/TsConfig/Page
+    :regex: /^.*Configuration\/TsConfig\/Page\/.*\.tsconfig$/
+    :shortDescription: Contains page TSconfig files. The path is convention, the files must end on .tsconfig.
+
     page TSconfig, see chapter :ref:`'page TSconfig' in the TSconfig Reference
     <t3tsref:PageTSconfig>`. Files should have the file extension
     :file:`.tsconfig`.
 
-Configuration/TsConfig/User
+..  typo3:file:: something.tsconfig
+    :scope: extension
+    :path: /Configuration/TsConfig/User
+    :regex: /^.*Configuration\/TsConfig\/User\/.*\.tsconfig$/
+    :shortDescription: Contains page TSconfig files. The path is convention, the files must end on .tsconfig.
+
     User TSconfig, see chapter :ref:`'user TSconfig' in the TSconfig Reference
     <t3tsref:UserTSconfig>`. Files should have the file extension
     :file:`.tsconfig`.

Documentation/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.rst

@@ -21,15 +21,17 @@
 TypoScript constants should be stored in a file called :file:`constants.typoscript`
 and TypoScript setup in a file called :file:`setup.typoscript`.
 
-
-..  directory-tree::
-    :level: 2
-    :show-file-icons: true
-
-    *   packages/my_extension/Configuration/TypoScript/
-
-        *   constants.typoscript
-        *   setup.typoscript
+..  typo3:file:: constants.typoscript
+    :scope: extension
+    :path: /Configuration/TypoScript
+    :regex: /^.*Configuration\/TypoScript\/.*constants\.typoscript/
+    :shortDescription: Contains the TypoScript constants of the extension. The path is convention, the file name mandatory.
+
+..  typo3:file:: setup.typoscript
+    :scope: extension
+    :path: /Configuration/TypoScript
+    :regex: /^.*Configuration\/TypoScript\/.*setup\.typoscript/
+    :shortDescription: Contains the TypoScript setup of the extension. The path is convention, the file name mandatory.
 
 These two files are made available for inclusion in TypoScript records with
 :php:`ExtensionManagementUtility::addStaticFile` in the file
@@ -38,6 +40,9 @@ These two files are made available for inclusion in TypoScript records with
 .. literalinclude:: _snippets/_sys_template.php
    :caption: EXT:my_extension/Configuration/TCA/Overrides/sys_template.php
 
+It is also possible to use subfolders or a differently named folders. The file
+names have to stay exactly the same including case.
+
 ..  warning::
     In Sites that use no Site set it is possible, though not recommended,
     to provide TypoScript that is always included.