[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 Fixes: TYPO3-Solr#4204
dkd-kaehm · Dec 12, 2024 · 4f7b9a7 · 4f7b9a7
1 parent 5d659dd
commit 4f7b9a7
Show file tree

Hide file tree

Showing 55 changed files with 112 additions and 261 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -84,6 +84,30 @@ jobs:
           path: /tmp/solrci-image.tar
           retention-days: 1
 
+  test_documentation:
+    name: test Documentation
+    runs-on: ubuntu-latest
+    ## @todo: remove `continue-on-error: true`, if Version matrix tables are fixed.
+    continue-on-error: true
+    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 --minimal-test
+
   tests:
     runs-on: ubuntu-latest
     needs: ci_bootstrapping
@@ -177,7 +201,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:
@@ -221,7 +245,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"
diff --git a/Build/generate_documentation.sh b/Build/generate_documentation.sh
@@ -12,23 +12,18 @@ 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)
+if ! docker run --rm --pull always -v "$(pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation "$@"; 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;
diff --git a/Documentation/Appendix/DockerTweaks.rst b/Documentation/Appendix/DockerTweaks.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _appendix-docker-tweaks:
 
 Appendix - Docker Tweaks

diff --git a/Documentation/Appendix/DynamicFieldTypes.rst b/Documentation/Appendix/DynamicFieldTypes.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _appendix-dynamic-fields:
 
 Appendix - Dynamic Fields

diff --git a/Documentation/Appendix/VersionMatrix.rst b/Documentation/Appendix/VersionMatrix.rst
@@ -1,4 +1,3 @@
-.. include:: /Includes.rst.txt
 .. _appendix-version-matrix:
 
 Appendix - Version Matrix

diff --git a/Documentation/Backend/Index.rst b/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
diff --git a/Documentation/Backend/ResultsPlugin.rst b/Documentation/Backend/ResultsPlugin.rst
@@ -1,4 +1,3 @@
-
 Results Plugin
 ==============
 

diff --git a/Documentation/Configuration/Index.rst b/Documentation/Configuration/Index.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-index:
 
 Configuration Reference

diff --git a/Documentation/Configuration/Reference/ExtensionSettings.rst b/Documentation/Configuration/Reference/ExtensionSettings.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-settings:
 
 Extension Configuration

diff --git a/Documentation/Configuration/Reference/SolrConnection.rst b/Documentation/Configuration/Reference/SolrConnection.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-solr-client:
 
 Solr Connection

diff --git a/Documentation/Configuration/Reference/TxSolr.rst b/Documentation/Configuration/Reference/TxSolr.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 tx_solr
 =======
 

diff --git a/Documentation/Configuration/Reference/TxSolrGeneral.rst b/Documentation/Configuration/Reference/TxSolrGeneral.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-general:
 
 tx_solr.general

diff --git a/Documentation/Configuration/Reference/TxSolrIndex.rst b/Documentation/Configuration/Reference/TxSolrIndex.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-index:
 
 tx_solr.index

diff --git a/Documentation/Configuration/Reference/TxSolrLogging.rst b/Documentation/Configuration/Reference/TxSolrLogging.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-logging:
 
 tx_solr.logging

diff --git a/Documentation/Configuration/Reference/TxSolrSearch.rst b/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.
-
-
diff --git a/Documentation/Configuration/Reference/TxSolrStatistics.rst b/Documentation/Configuration/Reference/TxSolrStatistics.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-statistics:
 
 tx_solr.statistics
@@ -102,4 +99,4 @@ statistics.queries.limit
 :Since: 12.0
 :Default: 100
 
-Number of records to read out search queries.
+Number of records to read out search queries.
diff --git a/Documentation/Configuration/Reference/TxSolrSuggest.rst b/Documentation/Configuration/Reference/TxSolrSuggest.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-suggest:
 
 tx_solr.suggest
@@ -30,7 +27,7 @@ suggestField
 Sets the Solr index field used to get suggestions from. A general advice is to use a field without stemming on it. For practical reasons this is currently the spell checker field.
 
 Note: With EXT:solr 11.1.0 ASCII folding and language depending normalization filters were introduced, but due to the special behaviour of the auto suggestions ascii-terms were not treated correctly. So with 11.1.3 the untouched tokens are also kept, as this might lead to duplicate
-suggestions, a new field for exact suggestions is introduced, if you want to avoid duplicates and use stricter suggestions, just configure `spellExact` as suggest field. 
+suggestions, a new field for exact suggestions is introduced, if you want to avoid duplicates and use stricter suggestions, just configure `spellExact` as suggest field.
 
 forceHttps
 ----------

diff --git a/Documentation/Configuration/Reference/TxSolrView.rst b/Documentation/Configuration/Reference/TxSolrView.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _conf-tx-solr-view:
 
 tx_solr.view

diff --git a/Documentation/Database/Index.rst b/Documentation/Database/Index.rst
@@ -5,7 +5,7 @@ Database indexes
 ----------------
 
 Some of the SQL statements performed on the pages table in TYPO3 perform extensive operations while copying
-page-trees. These operations can be speeded by by adding 2 indexes to the standard table pages.
+page-trees. These operations can be speed up by by adding 2 indexes to the standard table pages.
 
 The indexes are:
 * content_from_pid_deleted (content_from_pid, deleted),

diff --git a/Documentation/Development/Backend.rst b/Documentation/Development/Backend.rst
@@ -1,4 +1,3 @@
-
 ##########################
 Developing Backend Modules
 ##########################

diff --git a/Documentation/Development/Index.rst b/Documentation/Development/Index.rst
@@ -1,6 +1,3 @@
-.. include:: /Includes.rst.txt
-
-
 .. _development-index:
 
 

diff --git a/Documentation/Development/Indexing.rst b/Documentation/Development/Indexing.rst
@@ -1,5 +1,3 @@
-.. This file will be replaced from solrfluid later
-
 ========
 Indexing
 ========
@@ -41,7 +39,7 @@ The corresponding event listener class:
         }
     }
 
-For other records than pages, the PSR-14 Event :php:class:`ApacheSolrForTypo3\Solr\Event\Indexing\BeforeDocumentIsProcessedForIndexingEvent` can be used.
+For other records than pages, the PSR-14 Event :php:`ApacheSolrForTypo3\Solr\Event\Indexing\BeforeDocumentIsProcessedForIndexingEvent` can be used.
 
 AfterPageDocumentIsCreatedForIndexingEvent
 ------------------------------------------

diff --git a/Documentation/FAQ/Index.rst b/Documentation/FAQ/Index.rst
@@ -1,4 +1,3 @@
-.. include:: /Includes.rst.txt
 .. _faq-index:
 
 FAQ - Frequently Asked Questions
-Original file line number
+Diff line change
@@ -1,6 +1,3 @@
-    .. include:: /Includes.rst.txt
     tx_solr
     =======
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -1,6 +1,3 @@
		.. include:: /Includes.rst.txt


		.. _development-index:


Expand Down