[TASK] Improve syntax and titles in Extbase chapters (#5436)

Releases: main, 13.4

Author: linawolf

Documentation/ExtensionArchitecture/Extbase/Examples/Index.rst

@@ -1,8 +1,8 @@
 :navigation-title: Examples
-.. include:: /Includes.rst.txt
+..  include:: /Includes.rst.txt
 
-.. index:: Extbase; Examples
-.. _extbase_examples:
+..  index:: Extbase; Examples
+..  _extbase-examples:
 
 ================
 Extbase Examples
@@ -11,9 +11,13 @@ Extbase Examples
 ..  contents::
     :local:
 
+..  _extbase-examples-extensions:
+
 Example extensions
 ==================
 
+..  _extbase-examples-extensions-tea:
+
 Tea example
 -----------
 
@@ -23,25 +27,37 @@ unit/functional/acceptance testing and continuous integration.
 
 You can also use this extension to manage your collection of delicious teas.
 
+..  _extbase-examples-extensions-blog:
+
 Blog example
 ------------
 
-The extension :composer:`t3docs/blog-example` contains working examples of all the features documented in the :ref:`Extbase Reference <extbase_reference>` manual.
+The extension :composer:`t3docs/blog-example` contains working examples of all
+the features documented in the :ref:`Extbase Reference <extbase_reference>` manual.
 
-This extension should not be used as a base for building your own extension or used to blog in a live environment.
+This extension should not be used as a base for building your own extension
+or used to blog in a live environment.
 
-If you want to set up a blog, take a look at the :composer:`t3docs/blog-example` extension or combine :composer:`georgringer/news` with a comment extension of your choice.
+If you want to set up a blog, take a look at the :composer:`t3docs/blog-example`
+extension or combine :composer:`georgringer/news` with a comment extension of
+your choice.
+
+..  _extbase-examples-extensions-real-world:
 
 Real-world examples
 ===================
 
+..  _extbase-examples-user-module:
+
 Backend user module
 -------------------
 
 In the TYPO3 Core, the system extension :composer:`typo3/cms-beuser` has backend modules
 based on Extbase. It can therefore be used as a guide on how to develop
 backend modules with Extbase.
 
+..  _extbase-examples-extensions-news:
+
 News
 ----
 

Documentation/ExtensionArchitecture/Extbase/Index.rst

@@ -1,12 +1,13 @@
-.. include:: /Includes.rst.txt
-.. index::
-   pair: Extension development; Extbase
+:navigation-title: Extbase
 
-.. _extbase:
+..  include:: /Includes.rst.txt
+..  index::
+    pair: Extension development; Extbase
+..  _extbase:
 
-=======
-Extbase
-=======
+=====================================
+Extbase: Extension framework in TYPO3
+=====================================
 
 Extbase is an extension framework to create TYPO3 frontend plugins and TYPO3
 backend modules. Extbase can be used to develop extensions but it does not

Documentation/ExtensionArchitecture/Extbase/Introduction/Index.rst

@@ -1,17 +1,20 @@
 :navigation-title: Introduction
-.. include:: /Includes.rst.txt
-.. index::
-   pair: Extension development; Extbase introduction
 
-.. _extbase-introduction:
+..  include:: /Includes.rst.txt
+..  index::
+    pair: Extension development; Extbase introduction
+
+..  _extbase-introduction:
 
 ====================
 Extbase introduction
 ====================
 
-.. todo:: Refer to a good example, e.g. tea, blog_example?
+..  todo:: Refer to a good example, e.g. tea, blog_example?
+
+..  todo:: Add tips how to get more information or help
 
-.. todo:: Add tips how to get more information or help
+..  _extbase-introduction-what-is:
 
 What is Extbase?
 ================
@@ -43,13 +46,14 @@ Thus, many things, such as backend modules or plugins can be done "the Extbase
 way" or "the Core way". This is a design decision, the extension developer must
 make for the specific use case.
 
-.. attention::
+..  attention::
 
-   Extbase is one of many options in the "toolbox" of TYPO3 extension development.
+    Extbase is one of many options in the "toolbox" of TYPO3 extension development.
 
-   TYPO3 is flexible, often provides several approaches for one thing and it is
-   up to the extension developer to make an informed choice.
+    TYPO3 is flexible, often provides several approaches for one thing and it is
+    up to the extension developer to make an informed choice.
 
+..  _extbase-introduction-or-not:
 
 Extbase or not?
 ===============
@@ -61,20 +65,20 @@ guidance):
 
 Use Extbase if you:
 
-*  wish to get started quickly, e.g. using the
-   :ref:`extension_builder <extension-builder>`
-*  are a beginner or do not have much experience with TYPO3
-*  want to create a "classic" Extbase extension with plugins and (possibly)
-   backend modules (as created with the extension_builder)
+*   wish to get started quickly, e.g. using the
+    :ref:`extension_builder <extension-builder>`
+*   are a beginner or do not have much experience with TYPO3
+*   want to create a "classic" Extbase extension with plugins and (possibly)
+    backend modules (as created with the extension_builder)
 
 Do not use Extbase
 
-*  if performance might be an issue with the "classic" Extbase approach
-*  if there is no benefit from using the Extbase approach
-*  if you are writing an extension where Extbase does not add any or much value,
-   e.g. an extension consisting only of Backend modules, a site package, a
-   collection of content elements, an Extension which is used as a command line
-   tool.
+*   if performance might be an issue with the "classic" Extbase approach
+*   if there is no benefit from using the Extbase approach
+*   if you are writing an extension where Extbase does not add any or much value,
+    e.g. an extension consisting only of Backend modules, a site package, a
+    collection of content elements, an Extension which is used as a command line
+    tool.
 
 There is also the possibility to use a "mixed" approach, e.g. use Extbase
 controllers, but do not use the persistence of Extbase. Use TYPO3
@@ -89,7 +93,7 @@ using "lazy initialization" which is supported within Extbase.
 However, if you use the "mixed" approach, you will not get some of the
 advantages of Extbase and have to write more code yourself.
 
-.. seealso::
+..  seealso::
 
-   For more information to get started with Extension development, see
-   :ref:`extension-create-new`.
+    For more information to get started with Extension development, see
+    :ref:`extension-create-new`.

Documentation/ExtensionArchitecture/Extbase/Reference/Annotations.rst

@@ -1,11 +1,12 @@
-.. include:: /Includes.rst.txt
+:navigation-title: Annotations
 
-.. index:: Extbase; Annotations
-.. _extbase-annotations:
+..  include:: /Includes.rst.txt
+..  index:: Extbase; Annotations
+..  _extbase-annotations:
 
-===========
-Annotations
-===========
+======================
+Annotations in Extbase
+======================
 
 All available annotations for Extbase delivered by TYPO3 Core are placed within
 the namespace :php:`\TYPO3\CMS\Extbase\Annotation`.
@@ -16,12 +17,14 @@ for the annotation :php:`Lazy`:
 ..  literalinclude:: _Annotations/_Lazy.php
     :caption: EXT:blog_example/Classes/Domain/Model/Blog.php, modified
 
+..  _extbase-annotations-internal:
+
 Annotations provided by Extbase
 ===============================
 
 The following annotations are provided Extbase:
 
-.. _extbase-annotation-validate:
+..  _extbase-annotation-validate:
 
 Validate
 --------
@@ -39,7 +42,7 @@ Can be used in the context of a model property.
 `Validate` annotations for a controller action are executed additionally
 to possible domain model validators.
 
-.. _extbase-annotation-ignore-validation:
+..  _extbase-annotation-ignore-validation:
 
 IgnoreValidation
 ----------------
@@ -66,14 +69,14 @@ Read more about this on https://usetypo3.com/dtos-in-extbase/ or see a
 :abbr:`CRUD (Create, Read, Update, Delete)` example for this on
 https://github.com/garvinhicking/gh_validationdummy/
 
-.. _extbase-annotation-orm:
+..  _extbase-annotation-orm:
 
 ORM (object relational model) annotations
 ------------------------------------------
 
 The following annotations can only be used on model properties:
 
-.. _extbase-annotation-cascade:
+..  _extbase-annotation-cascade:
 
 Cascade
 ~~~~~~~
@@ -88,7 +91,7 @@ Extbase only supports the option "remove".
 ..  literalinclude:: _Annotations/_Cascade.php
     :caption: EXT:blog_example/Classes/Domain/Model/Blog.php, modified
 
-.. _extbase-annotation-transient:
+..  _extbase-annotation-transient:
 
 Transient
 ~~~~~~~~~
@@ -101,23 +104,23 @@ Transient
 ..  literalinclude:: _Annotations/_Transient.php
     :caption: EXT:blog_example/Classes/Domain/Model/Post.php, modified
 
-.. _extbase-annotation-lazy:
+..  _extbase-annotation-lazy:
 
 Lazy
 ~~~~
 
 :php:`\TYPO3\CMS\Extbase\Annotation\ORM\Lazy`: Marks model property to be loaded
 lazily on first access.
 
-.. note::
+..  note::
    Lazy loading can greatly improve the performance of your actions.
 
 **Example:**
 
 ..  literalinclude:: _Annotations/_Lazy.php
     :caption: EXT:blog_example/Classes/Domain/Model/Post.php, modified
 
-.. _extbase-annotation-combine:
+..  _extbase-annotation-combine:
 
 Combining annotations
 =====================

Documentation/ExtensionArchitecture/Extbase/Reference/Caching.rst

@@ -1,11 +1,12 @@
-.. include:: /Includes.rst.txt
+:navigation-title: Caching
 
-.. index:: Extbase; Caching
-.. _extbase_caching:
+..  include:: /Includes.rst.txt
+..  index:: Extbase; Caching
+..  _extbase_caching:
 
-==============================
-Caching
-==============================
+==========================
+Caching in Extbase plugins
+==========================
 
 Extbase clears the TYPO3 cache automatically for update processes. This is called
 *Automatic cache clearing*. This functionality is activated by default. If a domain object is

Documentation/ExtensionArchitecture/Extbase/Reference/Controller/ActionController.rst

@@ -1,11 +1,12 @@
-..  include:: /Includes.rst.txt
+:navigation-title: ActionController
 
+..  include:: /Includes.rst.txt
 ..  index:: Extbase; ActionController
 ..  _extbase-action-controller:
 
-================
-ActionController
-================
+==============================
+Extending the ActionController
+==============================
 
 Most Extbase controllers are based on the
 :php:`\TYPO3\CMS\Extbase\Mvc\Controller\ActionController`. It is theoretically
@@ -138,6 +139,8 @@ like this:
 ..  literalinclude:: _Snippets/_ActionController/_ext_localconf.php
     :caption: EXT:blog_example/ext_localconf.php (Excerpt)
 
+..  _extbase-action-controller-stop:
+
 Stop further processing in a controller's action
 ================================================
 
@@ -194,6 +197,8 @@ you can return a specific object through the :php:`responseFactory`:
     If you want to return a JSON response, see :ref:`extbase_responses` to achieve this
     with a special :php:`$this->jsonResponse()` method.
 
+..  _extbase-action-controller-events:
+
 Events
 ======
 

Documentation/ExtensionArchitecture/Extbase/Reference/Controller/ErrorAction.rst

@@ -1,8 +1,8 @@
-.. include:: /Includes.rst.txt
-.. index::
-   Extbase; Errors
-   Extbase; errorAction
-.. _extbase_error_action:
+..  include:: /Includes.rst.txt
+..  index::
+    Extbase; Errors
+    Extbase; errorAction
+..  _extbase_error_action:
 
 ============
 Error action
@@ -12,25 +12,27 @@ Extbase offers an out of the box handling for errors. Errors might occur during
 the mapping of incoming action arguments. For example, an argument can not
 be mapped or validation did not pass.
 
+..  _extbase_error_action-howto:
+
 How it works
 ============
 
-#. Extbase will try to map all arguments within :php:`ActionController`. During
-   this process arguments will also be validated.
+#.  Extbase will try to map all arguments within :php:`ActionController`. During
+    this process arguments will also be validated.
 
-#. If an error occurred, the class will call the :php:`$this->errorMethodName`
-   instead of determined :php:`$this->actionMethodName`.
+#.  If an error occurred, the class will call the :php:`$this->errorMethodName`
+    instead of determined :php:`$this->actionMethodName`.
 
-#. The default is to call :php:`errorAction()` which will:
+#.  The default is to call :php:`errorAction()` which will:
 
-   #. Clear cache in case :typoscript:`persistence.enableAutomaticCacheClearing` is
-      activated and current scope is frontend.
+    #.  Clear cache in case :typoscript:`persistence.enableAutomaticCacheClearing` is
+        activated and current scope is frontend.
 
-   #. Add an error :ref:`Flash Message <flash-messages>`
-      by calling :php:`addErrorFlashMessage()`.
-      It will in turn call :php:`getErrorFlashMessage()` to retrieve the
-      message to show.
+    #.  Add an error :ref:`Flash Message <flash-messages>`
+        by calling :php:`addErrorFlashMessage()`.
+        It will in turn call :php:`getErrorFlashMessage()` to retrieve the
+        message to show.
 
-   #. Return the user to the referring request URL. If no referrer exists, a plain text
-      message will be displayed, fetched from
-      :php:`getFlattenedValidationErrorMessage()`.
+    #.  Return the user to the referring request URL. If no referrer exists, a plain text
+        message will be displayed, fetched from
+        :php:`getFlattenedValidationErrorMessage()`.