[DOCS] Switch documentation rendering to PHP-based rendering

Known issues:

* Some RSTs missing index directive.
* Tables in `Documentation/Appendix/VersionMatrix.rst` are not renderable.
   See: TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#251

---

Currently it is not possible to use spans in tables, like it was possible on Sphix-Variant.
See: phpDocumentor/guides#1187

On the test `test_documentation` CI job, we want to generate the docs twice to be able to recognize the errors and warnings in the docs.
See: phpDocumentor/guides#1188

Fixes: TYPO3-Solr#4204

.github/workflows/ci.yml

@@ -96,10 +96,31 @@ jobs:
           name: solrci-image
           path: /tmp/solrci-image.tar
 
+  test_documentation:
+    name: test Documentation
+    runs-on: ubuntu-latest
+    steps:
+      # Workaround for issue with actions/checkout "wrong PR commit checkout". See: ci_bootstrapping job
+      - name: Checkout current state of Pull Request
+        if: github.event_name == 'pull_request'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Checkout current state of Branch
+        if: ${{ github.event_name == 'push' || github.event_name == 'schedule' }}
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      # End: Workaround for issue with actions/checkout...
+
+      - name: Test if the documentation will render without warnings
+        run: |
+          Build/generate_documentation.sh --no-progress
+
   tests:
     runs-on: ubuntu-latest
     needs: ci_bootstrapping
-    continue-on-error: ${{ contains(matrix.TYPO3, '-dev') }}
     strategy:
       matrix: ${{ fromJson(needs.ci_bootstrapping.outputs.matrix) }}
     env:
@@ -189,7 +210,7 @@ jobs:
     name: Publish new version to TER
     needs: tests
     if: startsWith(github.ref, 'refs/tags/')
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     env:
       TYPO3_API_TOKEN: ${{ secrets.TYPO3_API_TOKEN }}
     steps:
@@ -233,7 +254,7 @@ jobs:
           echo "Following message will be printed in TER as release description:"
           echo -e "$TER_COMMENT"
           if ! composer extension-build; then
-            >&2 echo -e "Something went wrong on bulding EXT:solr for NON-Composer mode. Please look in the job."
+            >&2 echo -e "Something went wrong on building EXT:solr for NON-Composer mode. Please look in the job."
             exit 13
           fi
           php ~/.composer/vendor/bin/tailor ter:publish --comment "$TER_COMMENT" "$RELEASE_VERSION"

Build/generate_documentation.sh

@@ -12,23 +12,25 @@ if ! command -v docker &> /dev/null; then
   exit 1
 fi
 
-if ! command -v dockrun_t3rd &> /dev/null; then
-  echo "The command \"dockrun_t3rd\" is not initialized on system."
-  echo "Making \"dockrun_t3rd\" available in current script."
-  if [[ "$(docker images -q ghcr.io/t3docs/render-documentation 2> /dev/null)" == "" ]]; then
-    docker pull ghcr.io/t3docs/render-documentation && docker tag ghcr.io/t3docs/render-documentation t3docs/render-documentation
-  fi
-  # shellcheck disable=SC2034
-  DOCKRUN_FN_QUIET=1
-  # shellcheck disable=SC1090
-  source <(docker run --rm ghcr.io/t3docs/render-documentation show-shell-commands)
+# @todo: Don't run the command twice: https://github.com/phpDocumentor/guides/issues/1188
+if ! docker run --rm --pull always -v "$(pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest \
+    --config=Documentation \
+    --fail-on-error "$@" \
+  || ! docker run --rm --pull always -v "$(pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest \
+    --config=Documentation \
+    --fail-on-log "$@"
+then
+  echo "Something went wrong on rendering the docs. Please check the output and affected documentation files of EXT:solr and fix them."
+  exit 1;
+else
+  echo "Great job, the documentation is fine."
 fi
 
-dockrun_t3rd makehtml-no-cache
-
 if [[ "$BUILD_DOCS_FOR_PRODUCTION" == 1 || "$BUILD_DOCS_FOR_PRODUCTION" == "true" ]]; then
   rm -Rf "${PRODUCTION_DOCS_PATH}" "Documentation.HTML"
-  mv -v "Documentation-GENERATED-temp/Result/project/0.0.0" "${PRODUCTION_DOCS_PATH}"
+  mv -v "Documentation-GENERATED-temp" "${PRODUCTION_DOCS_PATH}"
   ln -s "${PRODUCTION_DOCS_PATH}" "Documentation.HTML"
   rm -Rf "Documentation-GENERATED-temp"
 fi
+
+exit 0;

Documentation/Appendix/DockerTweaks.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _appendix-docker-tweaks:
 
 Appendix - Docker Tweaks

Documentation/Appendix/DynamicFieldTypes.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _appendix-dynamic-fields:
 
 Appendix - Dynamic Fields

Documentation/Appendix/VersionMatrix.rst

@@ -1,83 +1,25 @@
-.. include:: /Includes.rst.txt
 .. _appendix-version-matrix:
 
 Appendix - Version Matrix
 =========================
 
+.. seealso::
+
+    You are on docs for EXT:solr |release| version, please refer to `Version Matrix on main release <https://docs.typo3.org/p/apache-solr-for-typo3/solr/main/en-us/Appendix/VersionMatrix.html>`_ to see all versions.
+
 Supported versions
 ------------------
 
 List of EXT:solr versions and the matching versions of Apache Solr and TYPO3 that are supported:
 
-========= ========== ========== =========== =============== ================== ================================ =============== =============== =================
-       Basic components                Funding contribution extensions          Published funding contribution    Extensions         Solr configuration
-------------------------------- ---------------------------------------------- -------------------------------- --------------- ---------------------------------
-TYPO3     EXT:solr   EXT:tika   EXT:solrfal EXT:solrconsole EXT:solrdebugtools EXT:solrfluidgrouping            EXT:solrmlt     Apache Solr     Configset
-========= ========== ========== =========== =============== ================== ================================ =============== =============== =================
-12.4      12.0       12.0       12.0        12.0            12.0               N/A (integrated in EXT:solr)     12.0 (Ø)        9.7.0¹          ext_solr_12_0_0
-11.5      11.5       11.0       11.0        11.0            11.0               11.0                             11.0 (Ø)        8.11.3¹         ext_solr_11_5_0
-========= ========== ========== =========== =============== ================== ================================ =============== =============== =================
+=========  =============  ================  =============  =================  ====================  =======================  ================================  ===============  =================
+TYPO3      EXT:solr (↻)   EXT:solrmlt (↻)   EXT:tika (↻)   EXT:solrfal ($)    EXT:solrconsole ($)   EXT:solrdebugtools ($)   EXT:solrfluidgrouping ($↺)        Apache Solr      Configset
+=========  =============  ================  =============  =================  ====================  =======================  ================================  ===============  =================
+12.4       12.0           12.0 (Ø)          12.0           12.0               12.0                  12.0                     N/A (integrated in EXT:solr)      9.8.0¹           ext_solr_12_0_0
+=========  =============  ================  =============  =================  ====================  =======================  ================================  ===============  =================
 
+| $ - Funding contribution extensions. See: https://www.typo3-solr.com/solr-for-typo3/open-source-version/
+| $↺ - Published funding contribution. Previously as ($), but merged in EXT:solr core
+| ↻ - Open Source and financed by ($)
 | Ø  - not yet available
-| ᾱ  - non stable alpha release
-| β  - non stable beta release
-| rc - release candidate available
 | ¹  - recommended Apache Solr version, check version matrix in composer.json (`composer info:solr-versions`) for full list
-
-.. important::
-
-    | Non-stable releases are not available in TER, but
-    | via Composer or as a ZIP file attachment on GitHub `release <https://github.com/TYPO3-Solr/ext-solr/releases>`_ page.
-
-
-Extended Long Term Support (ELTS)
----------------------------------
-
-Since January 2022, we have been following the TYPO3 release cycles and actively support the last two TYPO3 versions; in addition, we offer ELTS support for
-selected older versions. The following table illustrates the offers and available and upcoming versions:
-
-========= =========== ========== =========== =============== ================== =============== ====================
-       Basic components                 Funding contribution extensions                 Solr configuration
--------------------------------- ---------------------------------------------- ------------------------------------
-TYPO3     EXT:solr    EXT:tika   EXT:solrfal EXT:solrconsole EXT:solrdebugtools Apache Solr     Configset
-========= =========== ========== =========== =============== ================== =============== ====================
-10.4      11.2.4+     10.0       10.0        10.0            10.0               9.5.0¹          ext_solr_11_2_0_elts
-9.5-10.4  11.0.9+     6.0.3+     8.0.2+      4.0.2+          1.1.3+             9.5.0¹          ext_solr_11_0_0_elts
-========= =========== ========== =========== =============== ================== =============== ====================
-
-Our Apache Solr for TYPO3 EB-partners newsletter will keep you updated!
-
-| Ø - not yet available
-| ¹ - recommended Apache Solr version, check version matrix in composer.json (`composer info:solr-versions`) for full list
-
-No longer supported versions
-----------------------------
-
-========= ========== ========= =========== =============== ================== =========== =========== ================
-TYPO3     EXT:solr   EXT:tika  EXT:solrfal EXT:solrconsole EXT:solrdebugtools EXT:solrmlt Apache Solr Configset
-========= ========== ========= =========== =============== ================== =========== =========== ================
-10.4      11.2.0-3   10.0      10.0        10.0            10.0               10.0        8.11        ext_solr_11_2_0
-10.4      11.1       10.0      10.0        10.0            10.0               10.0        8.9         ext_solr_11_1_0
-9.5-10.4  11.0.0-7   6.0.0-2   8.0.0-1     4.0.0-1         1.1.2              3.1         8.5         ext_solr_11_0_0
-9.5       10.0       5.0       7.0         3.0             1.1.1              3.0         8.2         ext_solr_10_0_0
-8.7-9.5   9.0        4.0       6.0         2.0             1.1.0              3.0         7.6         ext_solr_9_0_0
-8.7       8.1        3.1       5.1         1.0             1.0.0              2.0         6.6         ext_solr_8_1_0
-8.7       8.0        3.0       5.0         N/A             N/A                N/A         6.6         ext_solr_8_0_0
-8.7       7.5        2.4       4.2         N/A             N/A                N/A         6.6         ext_solr_7_5_0
-8.7       7.0        2.4       4.2         N/A             N/A                N/A         6.3         ext_solr_7_0_0
-========= ========== ========= =========== =============== ================== =========== =========== ================
-
-Obsolete versions
------------------
-
-========== ========= ========= =========== ============= ================ ================ =========== ======================== ======================== ============
-TYPO3      EXT:solr  EXT:tika  EXT:solrfal EXT:solrfluid EXT:solrgrouping EXT:solrmlt      Apache Solr Schema                   Solrconfig               Accessplugin
-========== ========= ========= =========== ============= ================ ================ =========== ======================== ======================== ============
-7.6 - 8.x  6.5       2.3       4.1         2.0           1.3              N/A              6.6.2       tx_solr-6-5-0--20171023  tx_solr-6-5-0--20171023  2.0
-7.6 - 8.7  6.1       2.3       4.1         2.0           1.3              N/A              6.3         tx_solr-6-1-0--20170206  tx_solr-6-1-0--20161220  2.0
-7.6        6.0       2.2       4.0         1.2           1.3              N/A              6.3         tx_solr-6-0-0--20161209  tx_solr-6-0-0--20161122  1.7
-7.6        5.1       2.1       3.2         1.2           1.3              N/A              4.10        tx_solr-5-1-0--20160725  tx_solr-4-0-0--20160406  1.3
-7.6        5.0       2.1       3.1         1.0           1.3              N/A              4.10        tx_solr-4-0-0--20160406  tx_solr-4-0-0--20160406  1.3
-7.6        4.0       2.1       3.0         N/A           1.2              N/A              4.10        tx_solr-4-0-0--20160406  tx_solr-4-0-0--20160406  1.3
-6.2 - 7.6  3.1       2.0       2.1         N/A           1.1              1.1              4.10        tx_solr-3-1-0--20150614  tx_solr-3-1-0--20151012  1.3
-========== ========= ========= =========== ============= ================ ================ =========== ======================== ======================== ============

Documentation/Backend/Index.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-backend:
 
 =======
@@ -21,5 +18,5 @@ In this chapter we want to go deeper and learn how to write more complex indexin
 	IndexInspector
 	PageProperties
 	Scheduler
-	Plugins.rst
-	ResultsPlugin.rst
+	Plugins
+	ResultsPlugin

Documentation/Backend/ResultsPlugin.rst

@@ -1,4 +1,3 @@
-
 Results Plugin
 ==============
 

Documentation/Configuration/Index.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-index:
 
 Configuration Reference

Documentation/Configuration/Reference/ExtensionSettings.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-settings:
 
 Extension Configuration

Documentation/Configuration/Reference/SolrConnection.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-solr-client:
 
 Solr Connection

Documentation/Configuration/Reference/TxSolr.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 tx_solr
 =======
 

Documentation/Configuration/Reference/TxSolrGeneral.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-general:
 
 tx_solr.general

Documentation/Configuration/Reference/TxSolrIndex.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-index:
 
 tx_solr.index

Documentation/Configuration/Reference/TxSolrLogging.rst

@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-logging:
 
 tx_solr.logging

Documentation/Configuration/Reference/TxSolrSearch.rst

@@ -1,4 +1,3 @@
-.. include:: /Includes.rst.txt
 .. _configuration.reference.solrsearch:
 
 tx_solr.search
@@ -853,11 +852,12 @@ When ```keepAllFacetsOnSelection``` is active the count of a facet do not get re
 
 The following example shows how to keep all options of all facets by keeping the real document count, even when it has zero options:
 
-```
-plugin.tx_solr.search.faceting.keepAllFacetsOnSelection = 1
-plugin.tx_solr.search.faceting.countAllFacetsForSelection = 1
-plugin.tx_solr.search.faceting.minimumCount = 0
-```````````````````````````````````````````````
+..  code-block:: typoscript
+
+    plugin.tx_solr.search.faceting.keepAllFacetsOnSelection = 1
+    plugin.tx_solr.search.faceting.countAllFacetsForSelection = 1
+    plugin.tx_solr.search.faceting.minimumCount = 0
+
 
 faceting.showAllLink.wrap
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -878,7 +878,7 @@ faceting.showEmptyFacets
 :Default: 0
 :Options: 0, 1
 
-By setting this option to 1, you will allow rendering of empty facets. Usually, if a facet does not offer any options to filter a resultset of documents, the facet header will not be shown. Using this option allows the header still to be rendered when no filter options are provided.
+By setting this option to 1, you will allow rendering of empty facets. Usually, if a facet does not offer any options to filter a result-set of documents, the facet header will not be shown. Using this option allows the header still to be rendered when no filter options are provided.
 
 faceting.urlParameterStyle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -889,7 +889,7 @@ faceting.urlParameterStyle
 :Default: index
 
 
-Allows to change the URL style of facets. 
+Allows to change the URL style of facets.
 
 Possible values:
 
@@ -983,10 +983,10 @@ faceting.facets.[facetName].additionalExcludeTags
 :Since: 9.0
 :Required: no
 
-The settings ``keepAllOptionsOnSelection``` and ``keepAllFacetsOnSelection``` are used internally to build exclude tags for facets in order to exclude the filters from the facet counts.
-This helps to keep the counts of a facet as expected by the user, in some usecases (Read also: http://yonik.com/multi-select-faceting/).
+The settings ```keepAllOptionsOnSelection``` and ```keepAllFacetsOnSelection``` are used internally to build exclude tags for facets in order to exclude the filters from the facet counts.
+This helps to keep the counts of a facet as expected by the user, in some use-cases (Read also: http://yonik.com/multi-select-faceting/).
 
-With the setting ``additionalExcludeTags``` you can add tags of factes that should be excluded from the counts as well.
+With the setting ```additionalExcludeTags``` you can add tags of facets that should be excluded from the counts as well.
 
 **Note:** This setting is only available for option facets by now.
 
@@ -1032,7 +1032,7 @@ faceting.facets.[facetName].excludeValues
 
 Defines a comma separated list of options that are excluded (The value needs to match the value in solr)
 
-Important: This setting only makes sence for option based facets (option, query, hierarchy)
+Important: This setting only makes sense for option based facets (option, query, hierarchy)
 
 
 faceting.facets.[facetName].facetLimit
@@ -1119,13 +1119,13 @@ faceting.facets.[facetName].sortBy
 :Type: String
 :TS Path: plugin.tx_solr.search.faceting.facets.[facetName].sortBy
 :Since: 1.2
-:Default: -
+:Default: by count of results
 :Options: alpha (aliases: index, lex)
 
-Sets how a single facet's options are sorted, by default they are sorted by number of results, highest on top.
+Sets how a single facet's options are sorted, by default they are sorted by count of results, highest on top.
 Facet options can also be sorted alphabetically by setting the option to alpha.
 
-Note: Since 9.0.0 it is possible to sort a facet by a function. This can be done be defining a metric and use that metric in the sortBy configuration. As sorting name you then need to use by convention "metrics_<metricName>"
+Note: Since 9.0.0 it is possible to sort a facet by a function. This can be done by defining a metric and use that metric in the sortBy configuration. As sorting name you then need to use by convention "metrics_<metricName>"
 
 Example:
 
@@ -1141,7 +1141,6 @@ Example:
     }
 
 
-
 faceting.facets.[facetName].manualSortOrder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1192,11 +1191,11 @@ faceting.facets.[facetName].minimumCount
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :Type: Integer
-:TS Path: plugin.tx_solr.search.faceting.facets.[facetName].minumumCount
+:TS Path: plugin.tx_solr.search.faceting.facets.[facetName].minimumCount
 :Since: 8.0
 :Default: 1
 
-Set's the minimumCount for a single facet. This can be usefull e.g. to set the minimumCount of a single facet to 0,
+Set's the minimumCount for a single facet. This can be useful e.g. to set the minimumCount of a single facet to 0,
 to have the options available even when there is result available.
 
 **Note**: This setting is only available for facets that are using the json faceting API of solr. By now this
@@ -1236,7 +1235,7 @@ faceting.facets.[facetName].includeInAvailableFacets
 
 By setting this option to 0, you can prevent rendering of a given facet within the list of available facets.
 
-This is useful if you render the facet somewhere eles on the page using the facet view helper and don't want the facet to be rendered twice.
+This is useful if you render the facet somewhere else on the page using the facet view helper and don't want the facet to be rendered twice.
 
 faceting.facets.[facetName].includeInUsedFacets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1394,7 +1393,7 @@ EXT:solr provides the following renderingInstructions that you can use in your p
 **FormatDate**:
 
 This rendering instruction can be used in combination with a date field or an integer field that hold a timestamp. You can use this rendering instruction to format the facet value on rendering.
-A common usecase for this is, when the datatype in Solr needs to be sortable (date or int) but you need to render the date as readable date option in the frontend:
+A common use-case for this is, when the datatype in Solr needs to be sortable (date or int) but you need to render the date as readable date option in the frontend:
 
 
 .. code-block:: typoscript
@@ -1633,5 +1632,3 @@ grouping.groups.[groupName].sortBy
 Allows to set a custom sorting for the group. Useful especially if you have already set `plugin.tx_solr.search.query.sortBy`. By default Solr will sort within a group by relevance, using this setting you can sort by any sortable field.
 
 Needs a Solr field name followed by asc for ascending order or desc for descending.
-
-