[TASK] List common configuration file locations as files (#5283) (#5301)

* [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

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

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

* Update Documentation/ExtensionArchitecture/FileStructure/Configuration/ContentSecurityPolicies.rst

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

* Update Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst

* Update Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst

* Update Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst

* Update Documentation/ExtensionArchitecture/FileStructure/Configuration/RequestMiddlewaresPhp.rst

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

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

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

* Apply suggestions from code review



* Apply suggestions from code review



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

---------

Co-authored-by: Lina Wolf <[email protected]>

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
 
-.. _extension-configuration-backend:
+..  include:: /Includes.rst.txt
+..  index::
+    Extension development; Configuration/Backend
+    Path; EXT:{extkey}/Configuration/Backend
 
-===============
-:file:`Backend`
-===============
+..  _extension-configuration-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 the URI 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

@@ -1,10 +1,10 @@
 .. include:: /Includes.rst.txt
-.. _extension-configuration-extbase:
-.. index:: Path; EXT:{extkey}/Configuration/Extbase
+..  _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

@@ -8,12 +8,17 @@
 
 This folder can contain the following files:
 
-:file:`Classes.php`
-===================
+..  _extension-configuration-extbase-persistence-classes:
+
+..  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

@@ -13,11 +13,17 @@
    :file:`Configuration/page.tsconfig` is automatically included for all
    pages.
 
-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

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 custom middleware for frontend and backend. Extensions that
+    add middleware or disable existing middleware are configured 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
+..  include:: /CodeSnippets/Manual/Extension/Configuration/RequestMiddlewares.rst.txt

Documentation/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.rst

@@ -1,12 +1,26 @@
-.. include:: /Includes.rst.txt
-.. index::
-   Extension development; Configuration/Services.yaml
-   Path; EXT:{extkey}/Configuration/Services.yaml
-.. _extension-configuration-services-yaml:
+..  include:: /Includes.rst.txt
+..  index::
+    Extension development; Configuration/Services.yaml
+    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,15 +1,17 @@
+: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.
+:ref:`TCA (Table Configuration Array) <t3tca:introduction>` data.
 
 All files in this directory are automatically included during the TYPO3
 :ref:`bootstrap <bootstrapping>`.
@@ -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 (Table Configuration Array), which initially defines the table <tablename>. Change TCA of 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, provided by the extension itself. **Must not** be used to change existing tables provided by other extensions.
 
 ..  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 (Table 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

@@ -2,18 +2,26 @@
 .. _extension-configuration-tsconfig:
 .. index:: Path; EXT:{extkey}/Configuration/TsConfig
 
-================================
+================
 :file:`TsConfig`
-================================
+================
 
-Configuration/TsConfig/Page
-  page TSconfig, see chapter :ref:`'page TSconfig' in the TSconfig Reference
-  <t3tsref:PageTSconfig>`. Files should have the file extension
-  :file:`.tsconfig`.
+..  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.
 
-.. index:: Path; EXT:{extkey}/Configuration/TsConfig/User
+    page TSconfig, see chapter :ref:`'page TSconfig' in the TSconfig Reference
+    <t3tsref:PageTSconfig>`. Files should have the file extension
+    :file:`.tsconfig`.
 
-Configuration/TsConfig/User
-  User TSconfig, see chapter :ref:`'user TSconfig' in the TSconfig Reference
-  <t3tsref:UserTSconfig>`. Files should have the file extension
-  :file:`.tsconfig`.
+..  typo3:file:: something.tsconfig
+    :scope: extension
+    :path: /Configuration/TsConfig/User
+    :regex: /^.*Configuration\/TsConfig\/User\/.*\.tsconfig$/
+    :shortDescription: Contains user 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 must have the file extension
+    :file:`.tsconfig`.