diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..79ac662e --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,17 @@ +name: test documentation + +on: [ push, pull_request ] + +jobs: + tests: + name: documentation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Test if the documentation will render without warnings + run: | + mkdir -p Documentation-GENERATED-temp \ + && docker run --rm --pull always -v $(pwd):/project \ + ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..75b642d6 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/Documentation-GENERATED-temp/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..011dc356 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,15 @@ +# Contribute to this extension + +## Preview documentation rendering + +You can render the documentation locally by calling: + +``` + make docs +``` + +The result is displayed in folder Documentation-GENERATED-temp + +# General TYPO3 Support + +If you have some general TYPO3 support questions or need help with TYPO3, please see https://typo3.org/help. diff --git a/Documentation/.editorconfig b/Documentation/.editorconfig index bd0b76d3..8099b01e 100644 --- a/Documentation/.editorconfig +++ b/Documentation/.editorconfig @@ -12,7 +12,7 @@ end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true indent_style = space -indent_size = 3 +indent_size = 4 max_line_length = 80 # MD-Files diff --git a/Documentation/Administration/AdditionalFields/Index.rst b/Documentation/Administration/AdditionalFields/Index.rst index 706e5ec5..fb4acd98 100644 --- a/Documentation/Administration/AdditionalFields/Index.rst +++ b/Documentation/Administration/AdditionalFields/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-additionalfields: diff --git a/Documentation/Administration/ArrayPath/Index.rst b/Documentation/Administration/ArrayPath/Index.rst index c8e8a430..99d4c354 100644 --- a/Documentation/Administration/ArrayPath/Index.rst +++ b/Documentation/Administration/ArrayPath/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-array-path: diff --git a/Documentation/Administration/Children/Index.rst b/Documentation/Administration/Children/Index.rst index b3f5267d..58ec90a0 100644 --- a/Documentation/Administration/Children/Index.rst +++ b/Documentation/Administration/Children/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-children: diff --git a/Documentation/Administration/Columns/Index.rst b/Documentation/Administration/Columns/Index.rst index 7b4b25d8..2c33c1db 100644 --- a/Documentation/Administration/Columns/Index.rst +++ b/Documentation/Administration/Columns/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-columns: @@ -14,21 +14,21 @@ In its simplest form this is just a reference to the external data's name: .. code-block:: php - 'code' => [ - 'exclude' => 0, - 'label' => 'LLL:EXT:externalimport_tut/locallang_db.xml:tx_externalimporttut_departments.code', - 'config' => [ - 'type' => 'input', - 'size' => 10, - 'max' => 4, - 'eval' => 'required,trim', - ], - 'external' => [ - 0 => [ - 'field' => 'code' - ] - ] - ], + 'code' => [ + 'exclude' => 0, + 'label' => 'LLL:EXT:externalimport_tut/locallang_db.xml:tx_externalimporttut_departments.code', + 'config' => [ + 'type' => 'input', + 'size' => 10, + 'max' => 4, + 'eval' => 'required,trim', + ], + 'external' => [ + 0 => [ + 'field' => 'code' + ] + ] + ], The properties for the columns configuration are described below. @@ -244,29 +244,29 @@ Description .. code-block:: xml - - - - A1 - 100.00 - - 000001 - - - ... - + + + + A1 + 100.00 + + 000001 + + + ... + getting the value in the :code:`` tag would require the following configuration: .. code-block:: php - 'external' => [ - 0 => [ - 'fieldNS' => 'urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2', - 'field' => 'LineExtensionAmount' - ] - ] + 'external' => [ + 0 => [ + 'fieldNS' => 'urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2', + 'field' => 'LineExtensionAmount' + ] + ] Scope Handle data (XML) @@ -303,57 +303,57 @@ Description .. code:: json - [ - { - "order": "000001", - "date": "2014-08-07", - "customer": "Conan the Barbarian", - "products": [ - { - "product": "000001", - "qty": 3 - }, - { - "product": "000005", - "qty": 1 - }, - { - "product": "000101", - "qty": 10 - }, - { - "product": "000102", - "qty": 2 - } - ] - }, - { - "order": "000002", - "date": "2014-08-08", - "customer": "Sonja the Red", - "products": [ - { - "product": "000001", - "qty": 1 - }, - { - "product": "000005", - "qty": 2 - }, - { - "product": "000202", - "qty": 1 - } - ] - } - ] + [ + { + "order": "000001", + "date": "2014-08-07", + "customer": "Conan the Barbarian", + "products": [ + { + "product": "000001", + "qty": 3 + }, + { + "product": "000005", + "qty": 1 + }, + { + "product": "000101", + "qty": 10 + }, + { + "product": "000102", + "qty": 2 + } + ] + }, + { + "order": "000002", + "date": "2014-08-08", + "customer": "Sonja the Red", + "products": [ + { + "product": "000001", + "qty": 1 + }, + { + "product": "000005", + "qty": 2 + }, + { + "product": "000202", + "qty": 1 + } + ] + } + ] The "products" field is actually a nested structure, from which we want to fetch the values from both `product` and `qty`. This can be achieved with the following configuration: .. code:: php - 'products' => [ + 'products' => [ 'exclude' => 0, 'label' => 'Products', 'config' => [ @@ -373,7 +373,7 @@ Description ... ] ] - ] + ] The keys to the configuration array correspond to the names of the columns where the values will be stored. The configuration for each element can use all the existing properties for retrieving data: @@ -518,7 +518,7 @@ Description .. code-block:: php - $GLOBALS['TCA']['fe_users']['columns']['starttime']['external'] = [ + $GLOBALS['TCA']['fe_users']['columns']['starttime']['external'] = [ 0 => [ 'field' => 'start_date', 'transformations' => [ @@ -533,7 +533,7 @@ Description ] ] ] - ]; + ]; The "userFunction" will be executed first (:code:`10`) and the "trim" next (:code:`20`). diff --git a/Documentation/Administration/GeneralTca/Index.rst b/Documentation/Administration/GeneralTca/Index.rst index a1eadee8..9505d751 100644 --- a/Documentation/Administration/GeneralTca/Index.rst +++ b/Documentation/Administration/GeneralTca/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-general-tca: @@ -13,7 +13,7 @@ The same keys need to be used again in the :ref:`column configuration [ 'general' => [ 0 => [ @@ -37,7 +37,7 @@ The same keys need to be used again in the :ref:`column configuration `, + When the special :code:`*` segment is used in an :ref:`arrayPath `, the resulting structure is always an array. If the :code:`arrayPath` target is actually a single value, this may not be desirable. When :code:`arrayPathFlatten` is set to :code:`true`, the result is preserved as a simple type. diff --git a/Documentation/Administration/Index.rst b/Documentation/Administration/Index.rst index 23e745e7..f6f28bdc 100644 --- a/Documentation/Administration/Index.rst +++ b/Documentation/Administration/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../Includes.txt +.. include:: /Includes.rst.txt .. _import-configuration: @@ -23,7 +23,7 @@ understand which part of the process it impacts. The names of the steps correspond to the :ref:`process steps `. There are some code examples throughout this chapter. They are -taken either from the :ref:`External Import Tutorial ` +taken either from the :ref:`External Import Tutorial ` or from the test extension: https://github.com/fsuter/externalimport_test. You are encouraged to refer to them for more examples and more details about each example (in the Tutorial). diff --git a/Documentation/Administration/LogCleanup/Index.rst b/Documentation/Administration/LogCleanup/Index.rst index 4c9d90a8..249d0a04 100644 --- a/Documentation/Administration/LogCleanup/Index.rst +++ b/Documentation/Administration/LogCleanup/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-log-cleanup: diff --git a/Documentation/Administration/Mapping/Index.rst b/Documentation/Administration/Mapping/Index.rst index ad064f22..e4b49d82 100644 --- a/Documentation/Administration/Mapping/Index.rst +++ b/Documentation/Administration/Mapping/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-mapping: @@ -201,9 +201,9 @@ Description .. note:: This property does nothing when used in combination with the - :ref:`MM property `, because we expect normalized + MM property, because we expect normalized data with one and denormalized data with the other. The chapter about - :ref:`mapping data ` hopefully helps understand this. + :ref:`mapping data ` hopefully helps understand this. Scope Transform data @@ -280,15 +280,15 @@ Here's an example TCA configuration. .. code-block:: php - $GLOBALS['TCA']['fe_users']['columns']['tx_externalimporttut_department']['external'] = [ - 0 => [ - 'field' => 'department', - 'mapping' => [ - 'table' => 'tx_externalimporttut_departments', - 'referenceField' => 'code' - ] - ] - ]; + $GLOBALS['TCA']['fe_users']['columns']['tx_externalimporttut_department']['external'] = [ + 0 => [ + 'field' => 'department', + 'mapping' => [ + 'table' => 'tx_externalimporttut_departments', + 'referenceField' => 'code' + ] + ] + ]; The value found in the "department" field of the external data will be matched to the "code" field of the "tx_externalimporttut_departments" table, @@ -309,26 +309,26 @@ The incoming data looks like: .. code-block:: xml - - - Long sword - attack,metal - - - Solar cream - - - Chain mail - defense,metal - - Out of structure - + + + Long sword + attack,metal + + + Solar cream + + + Chain mail + defense,metal + + Out of structure + and the external import configuration like: .. code-block:: php - $GLOBALS['TCA']['tx_externalimporttest_product']['columns']['tags']['external'] = [ + $GLOBALS['TCA']['tx_externalimporttest_product']['columns']['tags']['external'] = [ 'base' => [ 'xpath' => './self::*[@type="current"]/tags', 'transformations' => [ @@ -341,7 +341,7 @@ and the external import configuration like: ] ] ] - ]; + ]; The values in the :code:`` nodes will be split on the comma and each will be matched to a tag from "tx_externalimporttest_tag" diff --git a/Documentation/Administration/Transformations/Index.rst b/Documentation/Administration/Transformations/Index.rst index c1c2dc21..9d85fb91 100644 --- a/Documentation/Administration/Transformations/Index.rst +++ b/Documentation/Administration/Transformations/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-transformations: @@ -183,7 +183,7 @@ Description .. code-block:: php - $GLOBALS['TCA']['fe_users']['columns']['starttime']['external'] = [ + $GLOBALS['TCA']['fe_users']['columns']['starttime']['external'] = [ 0 => [ 'field' => 'start_date', 'transformations' => [ @@ -195,7 +195,7 @@ Description ] ] ] - ]; + ]; The definition of a user function takes three parameters: diff --git a/Documentation/Administration/UserRights/Index.rst b/Documentation/Administration/UserRights/Index.rst index b38be289..61dd2f13 100644 --- a/Documentation/Administration/UserRights/Index.rst +++ b/Documentation/Administration/UserRights/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _administration-user-rights: @@ -27,9 +27,9 @@ allowing a user to run synchronizations from the BE module and to define Scheduler tasks. This is found at the bottom of the "Access Lists" tab. .. figure:: ../../Images/UserPermissions.png - :alt: Specific user permissions + :alt: Specific user permissions - Setting specific permissions for the BE module + Setting specific permissions for the BE module DB mount points are not checked at this point, so the user may be diff --git a/Documentation/Appendix/Hooks/Index.rst b/Documentation/Appendix/Hooks/Index.rst index 47f7616b..d1f2850c 100644 --- a/Documentation/Appendix/Hooks/Index.rst +++ b/Documentation/Appendix/Hooks/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _appendix-hooks: @@ -34,9 +34,9 @@ processParameters .. code-block:: php - 'parameters' => [ - 'filename' => 'fileadmin/imports/data-%Y.csv' - ] + 'parameters' => [ + 'filename' => 'fileadmin/imports/data-%Y.csv' + ] Inside the hook, you could run :code:`strftime()` on the :code:`filename` parameter in order to replace "%Y" with the diff --git a/Documentation/Appendix/Index.rst b/Documentation/Appendix/Index.rst index ee451b04..0c171731 100644 --- a/Documentation/Appendix/Index.rst +++ b/Documentation/Appendix/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../Includes.txt +.. include:: /Includes.rst.txt .. _appendix: @@ -262,7 +262,7 @@ Scheduler tasks need to be updated. An upgrade wizard is provided in the Install Tool. It will automatically migrate existing old tasks. .. figure:: ../Images/UpdateWizard.png - :alt: The update wizard shows that there are tasks to update + :alt: The update wizard shows that there are tasks to update If there are no tasks to migrate, the External Import wizard will simply not show up. Otherwise just click on the "Execute" button and follow the instructions. diff --git a/Documentation/Developer/Api/Index.rst b/Documentation/Developer/Api/Index.rst index f94178f1..e362332b 100644 --- a/Documentation/Developer/Api/Index.rst +++ b/Documentation/Developer/Api/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _developer-api: @@ -27,8 +27,8 @@ instance of class :php:`\Cobweb\ExternalImport\Importer` and a single call. .. code-block:: php - $importer = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\Cobweb\ExternalImport\Importer::class); - $messages = $importer->import($table, $index, $rawData); + $importer = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\Cobweb\ExternalImport\Importer::class); + $messages = $importer->import($table, $index, $rawData); The call parameters are as follows: diff --git a/Documentation/Developer/CriticalExceptions/Index.rst b/Documentation/Developer/CriticalExceptions/Index.rst index 93d95c91..3431cf1e 100644 --- a/Documentation/Developer/CriticalExceptions/Index.rst +++ b/Documentation/Developer/CriticalExceptions/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _developer-critical-exceptions: diff --git a/Documentation/Developer/CustomHandlers/Index.rst b/Documentation/Developer/CustomHandlers/Index.rst index ed13174c..acf56e0d 100644 --- a/Documentation/Developer/CustomHandlers/Index.rst +++ b/Documentation/Developer/CustomHandlers/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _developer-handlers: diff --git a/Documentation/Developer/Events/Index.rst b/Documentation/Developer/Events/Index.rst index dd6a1366..549e19a5 100644 --- a/Documentation/Developer/Events/Index.rst +++ b/Documentation/Developer/Events/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _developer-events: @@ -16,7 +16,7 @@ This will cause their "parent" step to abort. More details in the chapter about :ref:`critical exceptions `. Any other exception will just be logged (depending on your logging configuration). -For usage, see the :ref:`core documentation about PSR-14 events `. +For usage, see the :ref:`core documentation about PSR-14 events `. .. _developer-events-process-connector-parameters: @@ -88,7 +88,7 @@ Substructure Preprocess a :code:`\DomNodeList` for XML-type data. Check the incoming type using the :php:`getDataType()` method. - .. php:method:: getImporter + .. php:method:: getImporter() Current instance of :php:`\Cobweb\ExternalImport\Importer`. diff --git a/Documentation/Developer/Index.rst b/Documentation/Developer/Index.rst index e269fe52..ff79c8ea 100644 --- a/Documentation/Developer/Index.rst +++ b/Documentation/Developer/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../Includes.txt +.. include:: /Includes.rst.txt .. _developer: diff --git a/Documentation/Developer/Steps/Index.rst b/Documentation/Developer/Steps/Index.rst index 73fba26d..71d877c5 100644 --- a/Documentation/Developer/Steps/Index.rst +++ b/Documentation/Developer/Steps/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _developer-steps: @@ -87,10 +87,10 @@ processed. To read the data, use: .. code-block:: php - // Read the raw data or... - $rawData = $this->getData()->getRawData(); - // Read the processed data - $records = $this->getData()->getRecords(); + // Read the raw data or... + $rawData = $this->getData()->getRawData(); + // Read the processed data + $records = $this->getData()->getRecords(); .. note:: @@ -101,10 +101,10 @@ If you manipulate the data, you need to store it explicitely: .. code-block:: php - // Store the raw data or... - $this->getData()->setRawData(); - // Store the processed data - $this->getData()->setRecords(); + // Store the raw data or... + $this->getData()->setRawData(); + // Store the processed data + $this->getData()->setRecords(); Another typical usage would be to interrupt the process entirely by setting the :code:`abortFlag` variable to :code:`true`, as mentioned @@ -135,7 +135,7 @@ This has two implications: .. code-block:: php - $this->getImporter()->setPreviewData(...); + $this->getImporter()->setPreviewData(...); The preview data can be of any type. @@ -145,7 +145,7 @@ This has two implications: .. code-block:: php - $this->getImporter()->isPreview(); + $this->getImporter()->isPreview(); #. Indicate that the :code:`records` of the :code:`Data` object are downloadable if it makes sense (see the :ref:`Data model API `). diff --git a/Documentation/Developer/UserFunctions/Index.rst b/Documentation/Developer/UserFunctions/Index.rst index 922fdbd4..d7cbf041 100644 --- a/Documentation/Developer/UserFunctions/Index.rst +++ b/Documentation/Developer/UserFunctions/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _developer-user-functions: diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt new file mode 100644 index 00000000..b5b5ca98 --- /dev/null +++ b/Documentation/Includes.rst.txt @@ -0,0 +1 @@ +.. You can put central messages to display on all pages here diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt deleted file mode 100644 index 4ba0dade..00000000 --- a/Documentation/Includes.txt +++ /dev/null @@ -1,19 +0,0 @@ -.. This is 'Includes.txt'. It is included at the very top of each and - every ReST source file in THIS documentation project (= manual). - -.. role:: aspect(emphasis) -.. role:: html(code) -.. role:: js(code) -.. role:: php(code) -.. role:: pn(emphasis) -.. role:: sep(strong) -.. role:: sql(code) -.. role:: typoscript(code) -.. role:: xml(code) -.. role:: yaml(code) - -.. role:: ts(typoscript) - :class: typoscript - -.. default-role:: code -.. highlight:: php \ No newline at end of file diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 853439f1..b5fe6ff6 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -1,4 +1,4 @@ -.. include:: Includes.txt +.. include:: /Includes.rst.txt .. _start: @@ -122,7 +122,6 @@ Tool for importing data from external sources into the TYPO3 database, using an Introduction/Index Installation/Index - Configuration/Index User/Index Administration/Index Developer/Index diff --git a/Documentation/Installation/Configuration/Index.rst b/Documentation/Installation/Configuration/Index.rst index aefcd9a1..27c57751 100644 --- a/Documentation/Installation/Configuration/Index.rst +++ b/Documentation/Installation/Configuration/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _installation-configuration: @@ -54,16 +54,16 @@ Debug .. code-block:: php - $GLOBALS['TYPO3_CONF_VARS']['LOG']['Cobweb']['ExternalImport']['Importer']['writerConfiguration'] = [ - // configuration for ERROR level log entries - \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [ - // add a FileWriter - \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [ - // configuration for the writer - 'logFile' => 'typo3temp/logs/typo3_import.log' - ] - ] - ]; + $GLOBALS['TYPO3_CONF_VARS']['LOG']['Cobweb']['ExternalImport']['Importer']['writerConfiguration'] = [ + // configuration for ERROR level log entries + \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [ + // add a FileWriter + \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [ + // configuration for the writer + 'logFile' => 'typo3temp/logs/typo3_import.log' + ] + ] + ]; Disable logging Disables logging by the TYPO3 Core Engine. By default diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst index 9a852b02..a0be048a 100644 --- a/Documentation/Installation/Index.rst +++ b/Documentation/Installation/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../Includes.txt +.. include:: /Includes.rst.txt .. _installation: @@ -61,7 +61,7 @@ Upgrade to 7.0.0 Support for old-style Connector services was droppped (i.e. connectors registered as TYPO3 Core Services). If you use custom connector services, make sure to update -them (see the :ref:`update instructions ` +them (see the :ref:`update instructions ` provided by extension "svconnector"). When editing Scheduler tasks in the External Import backend module, it is no longer diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst index 9de23045..4248022a 100644 --- a/Documentation/Introduction/Index.rst +++ b/Documentation/Introduction/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../Includes.txt +.. include:: /Includes.rst.txt .. _introduction: @@ -21,7 +21,7 @@ is to be able to use TYPO3 CMS standard functions on that data Connection to external applications is handled by a class of services called "connectors", the base of which is available as a separate extension -(:ref:`svconnector `). +(:ref:`svconnector `). Data from several external sources can be stored into the same table allowing data aggregation. @@ -40,7 +40,7 @@ is in a "palatable" format. If the external data requires a lot of processing, it is probably better to put it through an ETL or ESB tool first, and then import it into TYPO3 CMS. -Please also check extension :ref:`externalimport_tut ` +Please also check extension :ref:`externalimport_tut ` which provides a tutorial to this extension. More examples can be found in extension "externalimport_test", which is used diff --git a/Documentation/KnownProblems/Index.rst b/Documentation/KnownProblems/Index.rst index 20bf18aa..4c87bcd8 100644 --- a/Documentation/KnownProblems/Index.rst +++ b/Documentation/KnownProblems/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../Includes.txt +.. include:: /Includes.rst.txt .. _problems: diff --git a/Documentation/Sitemap.rst b/Documentation/Sitemap.rst index de4f3900..09d3c6f5 100644 --- a/Documentation/Sitemap.rst +++ b/Documentation/Sitemap.rst @@ -1,6 +1,6 @@ :template: sitemap.html -.. include:: Includes.txt +.. include:: /Includes.rst.txt ======= Sitemap diff --git a/Documentation/User/BackendModule/Index.rst b/Documentation/User/BackendModule/Index.rst index bad5ee9d..20c2aff0 100644 --- a/Documentation/User/BackendModule/Index.rst +++ b/Documentation/User/BackendModule/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-backend-module: @@ -22,10 +22,10 @@ synchronization" – displays a list of all synchronizable tables. The various features are summarized in the picture below. .. figure:: ../../Images/SynchronizableTablesOverview.png - :alt: BE module overview for synchronizable tables + :alt: BE module overview for synchronizable tables - Overview of the synchronizable tables view with all available - functions + Overview of the synchronizable tables view with all available + functions .. note:: @@ -49,18 +49,18 @@ and the third one displays the list of :ref:`steps that the process will go thro including any :ref:`custom steps `. .. figure:: ../../Images/InformationInspector.png - :alt: Inspecting TCA properties + :alt: Inspecting TCA properties - Viewing the details of the TCA properties for External Import + Viewing the details of the TCA properties for External Import If the configuration contains errors, they will be displayed in this detailed view. .. figure:: ../../Images/InformationInspectorWithErrors.png - :alt: Raised errors about wrong configuration + :alt: Raised errors about wrong configuration - Viewing errors in the External Import configuration + Viewing errors in the External Import configuration .. note:: @@ -81,9 +81,9 @@ module during that time, the process will abort. At the end of the process, flash messages will appear with the results: .. figure:: ../../Images/SynchronizationResults.png - :alt: Results of synchronization + :alt: Results of synchronization - Flash messages show the results of the synchronization + Flash messages show the results of the synchronization .. _user-backend-module-synchronizable-preview: @@ -106,9 +106,9 @@ Most importantly nothing permanent happens in preview mode. For example, data is not stored into the database. .. figure:: ../../Images/BackendPreview.png - :alt: Preview of a synchronization + :alt: Preview of a synchronization - The synchronization is run up to the Transform Data step and preview data is dumped to the screen + The synchronization is run up to the Transform Data step and preview data is dumped to the screen .. _user-backend-module-automation: @@ -137,9 +137,9 @@ as a number of seconds or using the same syntax as for cron jobs. .. figure:: ../../Images/AutomationDialog.png - :alt: Automation input form + :alt: Automation input form - Input form for setting automated synchronization parameters + Input form for setting automated synchronization parameters Clicking on the trash can icon cancels the automatic @@ -150,9 +150,9 @@ schedule for **all** tables. This means that all imports will be executed one after the other, in the order of priority. .. figure:: ../../Images/FullAutomation.png - :alt: Automating all tables + :alt: Automating all tables - Setting automated synchronization for all tables + Setting automated synchronization for all tables The same input form appears as for individual automation settings. @@ -175,9 +175,9 @@ view is purely informative as no action can be taken for these tables. Only the detailed configuration information can be accessed. .. figure:: ../../Images/NonSynchronizableTablesOverview.png - :alt: BE module overview for non-synchronizable tables + :alt: BE module overview for non-synchronizable tables - Overview for non-synchronizable tables, with just the information icon + Overview for non-synchronizable tables, with just the information icon .. _user-backend-module-logs: @@ -199,9 +199,9 @@ to the same run. There is not much more to it for now. It may gain new features in the future. .. figure:: ../../Images/LogModule.png - :alt: BE module overview for non-synchronizable tables + :alt: BE module overview for non-synchronizable tables - List of import log entries + List of import log entries .. note:: diff --git a/Documentation/User/Cache/Index.rst b/Documentation/User/Cache/Index.rst index 755c9796..56828546 100644 --- a/Documentation/User/Cache/Index.rst +++ b/Documentation/User/Cache/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-clear-cache: diff --git a/Documentation/User/Command/Index.rst b/Documentation/User/Command/Index.rst index a1c07200..a064e0a1 100644 --- a/Documentation/User/Command/Index.rst +++ b/Documentation/User/Command/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-command: @@ -48,7 +48,7 @@ A typical command will look like: .. code-block:: text - path/to/php path/to/bin/typo3 externalimport:sync --table=foo --index=bar --preview='Cobweb\\ExternalImport\\Step\\TransformDataStep' + path/to/php path/to/bin/typo3 externalimport:sync --table=foo --index=bar --preview='Cobweb\\ExternalImport\\Step\\TransformDataStep' This will stop the process after the :code:`TransformDataStep` and dump the transformed data in the standard output. Mind the correct syntax for defining the :code:`Step` class @@ -74,4 +74,4 @@ using the "debug" flag: .. code-block:: text - path/to/php path/to/bin/typo3 externalimport:sync --table=foo --index=bar --debug -v + path/to/php path/to/bin/typo3 externalimport:sync --table=foo --index=bar --debug -v diff --git a/Documentation/User/Debugging/Index.rst b/Documentation/User/Debugging/Index.rst index 792ae105..69c4e670 100644 --- a/Documentation/User/Debugging/Index.rst +++ b/Documentation/User/Debugging/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-debugging: diff --git a/Documentation/User/General/Index.rst b/Documentation/User/General/Index.rst index 3256555c..d6775029 100644 --- a/Documentation/User/General/Index.rst +++ b/Documentation/User/General/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-general: @@ -17,7 +17,7 @@ receive data from any kind of script using the provided API. Fetching data from an external source goes through a standardized process. Connecting to an external source is achieved using connector services -(:ref:`see extension svconnector `), that return the fetched data to +(:ref:`see extension svconnector `), that return the fetched data to the external import in either XML format or as a PHP array. Currently, the following connectors exist: @@ -26,7 +26,7 @@ following connectors exist: - **svconnector_json** for JSON source files - **svconnector_sql** for connecting to another database -It is quite easy to develop a :ref:`custom connector `, +It is quite easy to develop a :ref:`custom connector `, should that be needed. The external data is mapped to one or more TYPO3 CMS tables diff --git a/Documentation/User/Index.rst b/Documentation/User/Index.rst index 6fc7c154..ac7b8529 100644 --- a/Documentation/User/Index.rst +++ b/Documentation/User/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../Includes.txt +.. include:: /Includes.rst.txt .. _user: diff --git a/Documentation/User/MappingData/Index.rst b/Documentation/User/MappingData/Index.rst index 60840d5c..76f70dba 100644 --- a/Documentation/User/MappingData/Index.rst +++ b/Documentation/User/MappingData/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-mapping-data: @@ -48,7 +48,7 @@ one record in the TYPO3 database, possibly after some transformations. This is what this image tries to convey: .. figure:: ../../Images/ImportScenarios/SimplestScenario.svg - :alt: The simplest import scenario + :alt: The simplest import scenario One line of external data is read (red), it goes through some transformations (grey) @@ -69,7 +69,7 @@ and concatenates again (with a comma), all the values that were mapped. This is can be represented as: .. figure:: ../../Images/ImportScenarios/MultipleValuesSeparatorScenario.svg - :alt: Import scenario with multiple values separator + :alt: Import scenario with multiple values separator The external data (red) contains values that correspond to keys in the TYPO3 database. @@ -94,7 +94,7 @@ will be imported and the others will simply be discarded. This may not be what y want. A schema for this situation could be: .. figure:: ../../Images/ImportScenarios/DenormalizedNoMultipleRows.svg - :alt: Import scenario with denormalized data and no specific configuration + :alt: Import scenario with denormalized data and no specific configuration The black key and the white key represent the external keys. Among the four rows, @@ -121,7 +121,7 @@ as a comma-separated list of values). The result can be represented as: .. figure:: ../../Images/ImportScenarios/DenormalizedWithMultipleRows.svg - :alt: Import scenario with denormalized data and multiple rows activated + :alt: Import scenario with denormalized data and multiple rows activated Only two records are created but the many-to-many relations are preserved. @@ -145,7 +145,7 @@ are mutliple values, it will actually trigger an on-the-fly denormalization of the external data, as the schema below attempts to portray: .. figure:: ../../Images/ImportScenarios/SubstructureFieldsWithMultipleRows.svg - :alt: Import scenario with substructure fields and multiple rows activated + :alt: Import scenario with substructure fields and multiple rows activated The structured nested inside the external data (little yellow squares inside the @@ -182,7 +182,7 @@ In this case, the denormalized rows are not collapsed but each row is used to cr a separate child record: .. figure:: ../../Images/ImportScenarios/SubstructureFieldsWithChildRecords.svg - :alt: Import scenario with substructure fields and child recrods + :alt: Import scenario with substructure fields and child recrods Substructure fields may be used to fill children columns. diff --git a/Documentation/User/Overview/Index.rst b/Documentation/User/Overview/Index.rst index d338e44d..a9913c2b 100644 --- a/Documentation/User/Overview/Index.rst +++ b/Documentation/User/Overview/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-overview: @@ -9,9 +9,9 @@ Process overview The schema below provides an overview of the external import process: .. figure:: ../../Images/ExternalImportProcess.svg - :alt: Import process overview + :alt: Import process overview - The various steps of the external import process + The various steps of the external import process The process is comprised of steps, each of which corresponds to a diff --git a/Documentation/User/Reaction/Index.rst b/Documentation/User/Reaction/Index.rst index adaed71f..c527c308 100644 --- a/Documentation/User/Reaction/Index.rst +++ b/Documentation/User/Reaction/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-reaction: @@ -19,9 +19,9 @@ There can be more than one External Import reaction depending on your needs. Having several reactions allows you to distribute secret keys to different people. .. figure:: ../../Images/Reaction.png - :alt: Defining a reaction + :alt: Defining a reaction - Defining a reaction in the dedicated backend module + Defining a reaction in the dedicated backend module Choosing a configuration is optional. If one is chosen, the reaction will only @@ -72,12 +72,12 @@ pid (optional) Here is how it could look like (example made with Postman): .. figure:: ../../Images/ReactionRequestHeaders.png - :alt: Request headers + :alt: Request headers - The header with the URI, the accepted content type and the secret key + The header with the URI, the accepted content type and the secret key .. figure:: ../../Images/ReactionRequestBody.png - :alt: Request body + :alt: Request body - The body of the payload with the table name, configuration index and data to import + The body of the payload with the table name, configuration index and data to import diff --git a/Documentation/User/Scheduler/Index.rst b/Documentation/User/Scheduler/Index.rst index df01cbe5..39f8aba2 100644 --- a/Documentation/User/Scheduler/Index.rst +++ b/Documentation/User/Scheduler/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-scheduler: @@ -13,9 +13,9 @@ or directly from the Scheduler backend module. The taks provides two specific options: .. figure:: ../../Images/SchedulerTask.png - :alt: View of the External Import Scheduler task options + :alt: View of the External Import Scheduler task options - The options of the External Import Scheduler task + The options of the External Import Scheduler task Item to synchronize Choose which import configuration to automate. If you choose "all", all configurations will be synchronized diff --git a/Documentation/User/Troubleshooting/Index.rst b/Documentation/User/Troubleshooting/Index.rst index fec5f7e2..0799aa59 100644 --- a/Documentation/User/Troubleshooting/Index.rst +++ b/Documentation/User/Troubleshooting/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-troubleshooting: diff --git a/Documentation/User/Tutorial/Index.rst b/Documentation/User/Tutorial/Index.rst index 06e5f0e1..5de5191b 100644 --- a/Documentation/User/Tutorial/Index.rst +++ b/Documentation/User/Tutorial/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-tutorial: @@ -6,7 +6,7 @@ Tutorial ^^^^^^^^ -Extension :ref:`externalimport_tut ` provides +Extension :ref:`externalimport_tut ` provides an extensive tutorial about external import. It makes use of many configuration options. All examples are discussed in the extension's manual. diff --git a/Documentation/User/Webhook/Index.rst b/Documentation/User/Webhook/Index.rst index 103f3df9..55dabdce 100644 --- a/Documentation/User/Webhook/Index.rst +++ b/Documentation/User/Webhook/Index.rst @@ -1,4 +1,4 @@ -.. include:: ../../Includes.txt +.. include:: /Includes.rst.txt .. _user-webhook: @@ -21,9 +21,9 @@ essentially about setting the target URL and generating the "secret" using the field provided by TYPO3. .. figure:: ../../Images/Webhook.png - :alt: Defining a webhook + :alt: Defining a webhook - Defining a webhook in the dedicated backend module + Defining a webhook in the dedicated backend module The message is sent right after an import has completed, in the :php:`ReportStep` diff --git a/Documentation/guides.xml b/Documentation/guides.xml new file mode 100644 index 00000000..054a40a1 --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,18 @@ + + + + + diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..77dab54f --- /dev/null +++ b/Makefile @@ -0,0 +1,16 @@ +.PHONY: help +help: ## Displays this list of targets with descriptions + @echo "The following commands are available:\n" + @grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}' + +.PHONY: docs +docs: ## Generate projects documentation (from "Documentation" directory) + mkdir -p Documentation-GENERATED-temp + + docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + +.PHONY: test-docs +test-docs: ## Test the documentation rendering + mkdir -p Documentation-GENERATED-temp + + docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log