diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..3bf9683 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,102 @@ +name: documentation + +on: + pull_request: + +jobs: + + documentation: + name: "render documentation" + runs-on: ubuntu-22.04 + outputs: + comment_id: ${{ steps.find-comment.outputs.comment-id }} + documentation_url: ${{ steps.documentation-artifact.outputs.artifact-url }} + strategy: + fail-fast: false + permissions: + contents: write + steps: + - name: "Checkout" + uses: actions/checkout@v6 + + - name: Find Comment + uses: peter-evans/find-comment@v4 + id: find-comment + with: + issue-number: ${{ github.event.pull_request.number }} + comment-author: 'github-actions[bot]' + + - name: "Render documentation" + run: "Build/Scripts/runTests.sh -b podman -s renderDocumentation" + + - uses: actions/upload-artifact@v6 + id: documentation-artifact + with: + name: documentation-${{ github.event.pull_request.number }}-${{ github.run_id }} + path: Documentation-GENERATED-temp/ + compression-level: 9 + if-no-files-found: error + retention-days: 5 + include-hidden-files: true + overwrite: true + + + documentation-report: + name: "report rendered documentation" + runs-on: ubuntu-22.04 + strategy: + fail-fast: false + needs: [ documentation ] + steps: + + - name: Display information + run: | + echo "PR_ID.......: ${{ github.event.pull_request.number }}" + echo "COMMENT_ID..: ${{ needs.documentation.outputs.comment-id }}" + echo "ARTIFCAT_URL: ${{ needs.documentation.outputs.documentation_url }}" + + - name: Create Comment + uses: peter-evans/create-or-update-comment@v5 + # Skip if PR from fork (https://github.com/peter-evans/create-or-update-comment/issues/444) + # or comment-id not empty + if: github.repository == github.event.pull_request.head.repo.full_name && needs.documentation.outputs.comment_id == '' + with: + issue-number: ${{ github.event.pull_request.number }} + edit-mode: replace + body: |- + ## Documentation rendering + + You can find files attached to the below linked Workflow Run URL (Logs). + + Please note that files only stay for around 5 days! + + | Name | Link | + |---------------|-------------------------------------------------------------------------------------| + | Commit | ${{ github.event.pull_request.head.sha }} | + | Logs | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} | + | Documentation | ${{ needs.documentation.outputs.documentation_url }} | + + [badge]: https://img.shields.io/badge/Build-Success!-3fb950?logo=github&style=for-the-badge + + - name: Update Comment + # Skip if PR from fork (https://github.com/peter-evans/create-or-update-comment/issues/444) + # or comment-id empty + if: github.repository == github.event.pull_request.head.repo.full_name && needs.documentation.outputs.comment_id != '' + uses: peter-evans/create-or-update-comment@v5 + with: + comment-id: ${{ needs.documentation.outputs.comment_id }} + edit-mode: replace + body: |- + ## Documentation rendering + + You can find files attached to the below linked Workflow Run URL (Logs). + + Please note that files only stay for around 5 days! + + | Name | Link | + |---------------|-------------------------------------------------------------------------------------| + | Commit | ${{ github.event.pull_request.head.sha }} | + | Logs | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} | + | Documentation | ${{ needs.documentation.outputs.documentation_url }} | + + [badge]: https://img.shields.io/badge/Build-Failure!-f85149?logo=github&style=for-the-badge diff --git a/Build/Scripts/runTests.sh b/Build/Scripts/runTests.sh index be66b7e..b395b93 100755 --- a/Build/Scripts/runTests.sh +++ b/Build/Scripts/runTests.sh @@ -566,7 +566,7 @@ case ${TEST_SUITE} in SUITE_EXIT_CODE=$? ;; renderDocumentation) - ${CONTAINER_BIN} run ${CONTAINER_INTERACTIVE} --pull always -v ${ROOT_DIR}:/project -it ${IMAGE_RSTRENDERING} --config=Documentation + ${CONTAINER_BIN} run ${CONTAINER_COMMON_PARAMS} --name rendering-documentation-${SUFFIX} --pull always -w /project -v ${ROOT_DIR}:/project -it ${IMAGE_RSTRENDERING} --fail-on-error --no-progress --config=Documentation Documentation SUITE_EXIT_CODE=$? ;; phpstan) diff --git a/Documentation/Administration/Configuration/Index.rst b/Documentation/Administration/Configuration/Index.rst index 2b65e48..856337d 100644 --- a/Documentation/Administration/Configuration/Index.rst +++ b/Documentation/Administration/Configuration/Index.rst @@ -1,5 +1,3 @@ -.. include:: /Includes.rst.txt - .. _configuration: Configuration diff --git a/Documentation/Administration/Index.rst b/Documentation/Administration/Index.rst index 7474eca..32852cd 100644 --- a/Documentation/Administration/Index.rst +++ b/Documentation/Administration/Index.rst @@ -1,5 +1,3 @@ -.. include:: /Includes.rst.txt - .. _administration: ============== @@ -12,3 +10,4 @@ Administration Installation/Index Configuration/Index + Updates/Index diff --git a/Documentation/Administration/Installation/Index.rst b/Documentation/Administration/Installation/Index.rst index f41852b..912426c 100644 --- a/Documentation/Administration/Installation/Index.rst +++ b/Documentation/Administration/Installation/Index.rst @@ -1,5 +1,3 @@ -.. include:: /Includes.rst.txt - .. _installation: Installation @@ -8,28 +6,75 @@ Installation The extension has to be installed like any other TYPO3 CMS extension. You can download the extension using one of the following methods: -#. **Use composer**: - Run +.. tabs:: + + .. group-tab:: composer + + .. code-block:: bash + :caption: only the extension itself + + composer require -W \ + 'web-vision/deepl-write':'~2.0.0@dev' + + .. code-block:: bash + :caption: requiring depending TYPO3 extensions along the way + + composer require -W \ + 'web-vision/deeplcom-deepl-php':'~1.18.0@dev' \ + 'web-vision/deepl-base':'~2.0.0@dev' \ + 'web-vision/deepl-write':'~2.0.0@dev' + + .. tip:: - .. code-block:: bash + :guilabel:`~2.0.0@dev` is the recommended version constraint to use, which + locks the installable version down on :guilabel:`minor level (2.0)` having + :guilabel:`2.0.0` as lowest patchlevel version. :guilabel:`@dev` in general + would allow to install a possible development version and automatically + switch to the stable release in case :guilabel:`minimum-stability: "dev"` + and :guilabel:`prefer-stable: true` is configured in the root + :guilabel:`composer.json` file. - composer require -W 'web-vision/deepl-write':'^2.0' + :guilabel:`-W` automatically installs required transient dependencies, for + example: - in your TYPO3 installation. + * :guilabel:`web-vision/deepl-base` and + * :guilabel:`web-vision/deeplcom-deepl-php` -#. **Get it from the Extension Manager**: - Switch to the module :guilabel:`Admin Tools > Extensions`. - Switch to :guilabel:`Get Extensions` and search for the extension key - *deepltranslate_core* and import the extension from the repository. + .. note:: -#. **Get it from typo3.org**: - You can always get current version from `TER`_ by downloading the zip - version. Upload the file afterwards in the Extension Manager. + **Be aware** that aforementioned version constraints may be outdated, look up + actual version by checking the `packagist.org `_ + meta-data repository. -The extension then needs to be :ref:`configured ` -in order to display translation buttons in the desired languages. + * `packagist.org - web-vision/deepl-write `_ + * `packagist.org - web-vision/deepl-base `_ + * `packagist.org - web-vision/deeplcom-deepl-php `_ + + .. group-tab:: Extension Manager + + #. Switch to the module :guilabel:`System > Extensions`. + #. Switch to :guilabel:`Get Extensions` + #. Search for the extension key :guilabel:`deepl_write` + #. Import the extension from the repository. + + .. note:: + + For TYPO3 v13 navigate :guilabel:`Admin Tools > Extensions` to + find the **Extension Manager**. + + .. group-tab:: Upload ZIP (TER) + + #. Get current version from `TER`_ by downloading the zip version. + Alternatively, get the zip from the `Github Releases`_ page. + #. Switch to the module :guilabel:`System > Extensions`. + #. Enable upload :guilabel:`Upload Extension` + #. Select or drag extension ZIP archive and upload the file .. _TER: https://extensions.typo3.org/extension/deepl_write +.. _Github Releases: https://github.com/web-vision/deepl-write/releases + +The extension then needs to be :ref:`configured ` in order to +use the DeepL Write features. Compatibility ------------- @@ -37,5 +82,5 @@ Compatibility DeepL Write supports: .. csv-table:: Changes - :header: "DeepL Write version","TYPO3 Version","PHP version(s)","Supported" + :header: "DeepL Write version","TYPO3 Version","PHP version","Supported","Composer","TER" :file: Files/versionSupport.csv diff --git a/Documentation/Administration/Updates/Index.rst b/Documentation/Administration/Updates/Index.rst new file mode 100644 index 0000000..a9a7f3e --- /dev/null +++ b/Documentation/Administration/Updates/Index.rst @@ -0,0 +1,12 @@ +.. _updates: +.. _upgrades: + +======== +Upgrades +======== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + UpgradeFrom1To2 diff --git a/Documentation/Administration/Updates/UpgradeFrom1To2.rst b/Documentation/Administration/Updates/UpgradeFrom1To2.rst new file mode 100644 index 0000000..be2ce8f --- /dev/null +++ b/Documentation/Administration/Updates/UpgradeFrom1To2.rst @@ -0,0 +1,41 @@ +.. _upgrade1to2: + +================== +Upgrade 1.x to 2.x +================== + +The `2.x` version drops support for TYPO3 v12 and adds support for TYPO3 v14, +see :ref:`Breaking: Removed TYPO3 v12 support ` and +:ref:`Feature: Added TYPO3 v14 support `. + +Apart from the changed supported TYPO3 versions the functionality stayed the +same and no greater actions are needed. + +composer-mode +============= + +.. code-block:: bash + + composer require -W \ + "web-vision/deepl-write":"2.0.*@dev" + +classic-mode +============ + +#. **Get it from the Extension Manager**: + Switch to the module :guilabel:`System > Extensions`. + Switch to :guilabel:`Get Extensions` and search for the extension key + *deepl_write* and import the extension from the repository. + +#. **Get it from typo3.org**: + You can always get current version from `TER`_ by downloading the zip + version. Upload the file afterwards in the Extension Manager. + +#. **Get it from GitHub release**: + TER upload archives are added to the corresponding GitHub release page, + in case you need to download or update the extension and `GITHUB_RELEASES`_ + is down or not reachable. + + +.. _TER: https://extensions.typo3.org/extension/deepl_write +.. _GITHUB_RELEASES: https://github.com/web-vision/deepl-write/releases/ diff --git a/Documentation/Changelog/2.0/Breaking-RemovedTYPO3V12Support.rst b/Documentation/Changelog/2.0/Breaking-RemovedTYPO3V12Support.rst new file mode 100644 index 0000000..75f15e0 --- /dev/null +++ b/Documentation/Changelog/2.0/Breaking-RemovedTYPO3V12Support.rst @@ -0,0 +1,35 @@ +.. _breaking-1783314229: + +=================================== +Breaking: Removed TYPO3 v12 support +=================================== + +Description +=========== + +Support for TYPO3 v12 has been removed for `2.x` based on our dual +TYPO3 core version support per major version as casual support matrix. + +This includes removing code paths and configurations only required for +TYPO3 v12. + +Impact +====== + +TYPO3 v12 or older instances cannot update to the `2.x` version and are +required to upgrade TYPO3 to be able to install the next version of the +`EXT:deepl_write` together with `EXT:deepl-base (2.x)` and related packages +when released in a compatible version. + +Extension cannot be installed in that version but does not break otherwise. + +Affected installations +====================== + +TYPO3 v12 or older instances with `EXT:deepl_write` version `1.x`. + +Migration +========= + +Upgrade TYPO3 to supported version for `2.x` beforehand or in the same step +with upgrading/installing `EXT:deepl_write`. diff --git a/Documentation/Changelog/2.0/Feature-AddedTYPO3v14Support.rst b/Documentation/Changelog/2.0/Feature-AddedTYPO3v14Support.rst new file mode 100644 index 0000000..2b681b0 --- /dev/null +++ b/Documentation/Changelog/2.0/Feature-AddedTYPO3v14Support.rst @@ -0,0 +1,38 @@ +.. _feature-1783314230: + +================================ +Feature: Added TYPO3 v14 Support +================================ + +Description +=========== + +:guilabel:`TYPO3 v14.3.*` has been added coming with following changes: + +Handling and visual difference between TYPO3 v13 and v14 +-------------------------------------------------------- + +For `TYPO3 v14` the streamlined and revamped overall localization handling is +adopted, implementing the `LocalizationHandlerInterface` and making use of the +new `Localization Handler` feature. That means, that the look and feel is +different based on the used TYPO3 version even with the same extension version. +Some examples: + +* TYPO3 v14 localization handler selection: + + .. figure:: /Images/Editor/deeplwrite-localization-handler-v14.png + :alt: Select `DeepL Write` localization handler in TYPO3 v14 + +* TYPO3 v13 localization mode selection in `PageLayout module`: + + .. figure:: /Images/Editor/deeplwrite-localization-mode-v13.png + :alt: Select `DeepL Write` localization mode in TYPO3 v13 + +Impact +====== + +:guilabel:`web-vision/deepl-write` can now be installed and used in +:guilabel:`TYPO3 v14.3` instances. + +Supported features are completely available for TYPO3 v13 and v14, except +that generic TYPO3 handling is used provided by these versions. diff --git a/Documentation/Changelog/2.0/Index.rst b/Documentation/Changelog/2.0/Index.rst new file mode 100644 index 0000000..c355b60 --- /dev/null +++ b/Documentation/Changelog/2.0/Index.rst @@ -0,0 +1,52 @@ +:template: changelogOverview.html + +.. _changelog-2-0: + +2.0 Changes +=========== + +**Table of contents** + +.. contents:: + :local: + :depth: 1 + +Breaking Changes +^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :glob: + + Breaking-* + +Features +^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :glob: + + Feature-* + +Deprecation +^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :glob: + + Deprecation-* + +Important +^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :glob: + + Important-* diff --git a/Documentation/Changelog/Changelog-2-combined.rst b/Documentation/Changelog/Changelog-2-combined.rst new file mode 100644 index 0000000..7da5c47 --- /dev/null +++ b/Documentation/Changelog/Changelog-2-combined.rst @@ -0,0 +1,53 @@ +.. _changelog-v2-byType: + +=================== +2.x Changes by type +=================== + +This lists all changes to the DeepL Write extension of minor versions +grouped by their type. + +.. contents:: Table of contents +.. _changelog-v2-bc: +Breaking Changes +================ + +.. menu:: + :maxdepth: 3 + :titlesonly: + :glob: + + Changelog/2.*/Breaking-* + +.. _changelog-v2-feat: +Features +======== + +.. menu:: + :maxdepth: 3 + :titlesonly: + :glob: + + Changelog/2.*/Feature-* + +.. _changelog-v2-dep: +Deprecations +============ + +.. menu:: + :maxdepth: 3 + :titlesonly: + :glob: + + Changelog/2.*/Deprecation-* + +.. _changelog-v2-imp: +Important notes +=============== + +.. menu:: + :maxdepth: 3 + :titlesonly: + :glob: + + /Changelog/2.*/Important-* diff --git a/Documentation/Changelog/Changelog-2.rst b/Documentation/Changelog/Changelog-2.rst new file mode 100644 index 0000000..45bdb11 --- /dev/null +++ b/Documentation/Changelog/Changelog-2.rst @@ -0,0 +1,21 @@ +.. _changelog-v2: + +============ +ChangeLog v2 +============ + +Every change to the :guilabel:`web-vision/deepl-write` extension is documented here. + +.. toctree:: + :titlesonly: + + 2.0/Index + +Also available +-------------- + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + Changelog-2-combined diff --git a/Documentation/Changelog/Index.rst b/Documentation/Changelog/Index.rst new file mode 100644 index 0000000..ee90f28 --- /dev/null +++ b/Documentation/Changelog/Index.rst @@ -0,0 +1,13 @@ +.. _changelog: + +========= +ChangeLog +========= + +Every change to the :guilabel:`web-vision/deepl-write` extension is documented here. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Changelog-2 diff --git a/Documentation/Files/versionSupport.csv b/Documentation/Files/versionSupport.csv index 88becb6..52caa23 100644 --- a/Documentation/Files/versionSupport.csv +++ b/Documentation/Files/versionSupport.csv @@ -1,4 +1,4 @@ -"1.x.x","13","8.2, 8.3, 8.4, 8.5","yes" -"1.x.x","12","8.1, 8.2, 8.3, 8.4","yes" - - +"2.x","14.3.x","8.2, 8.3, 8.4, 8.5","yes","web-vision/deepl-write","deepl_write" +"2.x","13.4.x","8.2, 8.3, 8.4, 8.5","yes","web-vision/deepl-write","deepl_write" +"1.x","13.4.x","8.2, 8.3, 8.4, 8.5","yes","web-vision/deepl-write","deepl_write" +"1.x","12.4.x","8.1, 8.2, 8.3, 8.4","yes","web-vision/deepl-write","deepl_write" diff --git a/Documentation/Images/Editor/deeplwrite-localization-handler-v14.png b/Documentation/Images/Editor/deeplwrite-localization-handler-v14.png new file mode 100644 index 0000000..5e90af0 Binary files /dev/null and b/Documentation/Images/Editor/deeplwrite-localization-handler-v14.png differ diff --git a/Documentation/Images/Editor/deeplwrite-localization-mode-v13.png b/Documentation/Images/Editor/deeplwrite-localization-mode-v13.png new file mode 100644 index 0000000..aae64f1 Binary files /dev/null and b/Documentation/Images/Editor/deeplwrite-localization-mode-v13.png differ diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt deleted file mode 100644 index 210ac57..0000000 --- a/Documentation/Includes.rst.txt +++ /dev/null @@ -1,34 +0,0 @@ -.. More information about this file: - https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt - -.. ---------- -.. text roles -.. ---------- - -.. role:: aspect(emphasis) -.. role:: bash(code) -.. role:: html(code) -.. role:: js(code) -.. role:: php(code) -.. role:: rst(code) -.. role:: sep(strong) -.. role:: sql(code) - -.. role:: tsconfig(code) - :class: typoscript - -.. role:: typoscript(code) -.. role:: xml(code) - :class: html - -.. role:: yaml(code) - -.. default-role:: code - -.. --------- -.. highlight -.. --------- - -.. By default, code blocks use PHP syntax highlighting - -.. highlight:: php diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 48362c6..331a133 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -1,8 +1,8 @@ -.. include:: /Includes.rst.txt +.. _start: -========================= - DeepL Write -========================= +=========== +DeepL Write +=========== :Extension key: deepl_write @@ -26,20 +26,62 @@ |today| :License: - This document is published under the Open Content License - available from http://www.opencontent.org/opl.shtml + This document is published under the + `Open Publication License `__. - The content of this document is related to TYPO3, - a GNU/GPL CMS/Framework available from `www.typo3.org `_. +---- -**Table of Contents** +This extension integrates the `DeepL Write / Rephrase API `_ +into the TYPO3 backend to improve texts, adjust their tone and writing style or +translate them into simple language, both while editing RTE fields and while +localizing records. + +---- + +.. card-grid:: + :columns: 1 + :columns-md: 2 + :gap: 4 + :class: pb-4 + :card-height: 100 + + .. card:: :ref:`Introduction ` + + Introduction to the extension, general information. + + .. card:: :ref:`Administration ` + + Install or upgrade :guilabel:`deepl_write`, learn how to configure + the extension. + + .. card:: :ref:`Reference ` + + In-depth reference about certain aspects of this extension: + + * :guilabel:`Extension configuration` + + .. card:: :ref:`Known Issues ` + + Known issues and information about them. + + .. card:: :ref:`Changelog ` + + Learn about what have changed and what actions are required to process. .. toctree:: - :maxdepth: 5 + :maxdepth: 2 :titlesonly: - :glob: + :hidden: Introduction/Index Administration/Index Reference/Index KnownIssues/Index + Changelog/Index + +.. Meta Menu + +.. toctree:: + :hidden: + + Sitemap diff --git a/Documentation/Introduction/About/Index.rst b/Documentation/Introduction/About/Index.rst index 6f2df5f..555baf2 100644 --- a/Documentation/Introduction/About/Index.rst +++ b/Documentation/Introduction/About/Index.rst @@ -1,5 +1,3 @@ -.. include:: /Includes.rst.txt - .. _whatDoesItDo: What does it do? diff --git a/Documentation/Introduction/Contribution/Index.rst b/Documentation/Introduction/Contribution/Index.rst index 03890da..8be4d86 100644 --- a/Documentation/Introduction/Contribution/Index.rst +++ b/Documentation/Introduction/Contribution/Index.rst @@ -1,5 +1,3 @@ -.. include:: /Includes.rst.txt - .. _contribution: Contribution diff --git a/Documentation/KnownIssues/Index.rst b/Documentation/KnownIssues/Index.rst index 8ed89b5..263a544 100644 --- a/Documentation/KnownIssues/Index.rst +++ b/Documentation/KnownIssues/Index.rst @@ -1,8 +1,6 @@ -.. include:: /Includes.rst.txt - -.. _knownissues: +.. _knownIssues: Known Issues ============ -None so far. If you find an issue, feel free to :ref:`contribute `. +None so far. If you find an issue, feel free to :ref:`contribute `. diff --git a/Documentation/Reference/ExtensionConfiguration/Index.rst b/Documentation/Reference/ExtensionConfiguration/Index.rst index af99ee1..b5a6ed3 100644 --- a/Documentation/Reference/ExtensionConfiguration/Index.rst +++ b/Documentation/Reference/ExtensionConfiguration/Index.rst @@ -1,5 +1,3 @@ -.. include:: /Includes.rst.txt - .. _extensionConfiguration: ======================= diff --git a/Documentation/Sitemap.rst b/Documentation/Sitemap.rst new file mode 100644 index 0000000..69e6982 --- /dev/null +++ b/Documentation/Sitemap.rst @@ -0,0 +1,7 @@ +:template: sitemap.html + +======= +Sitemap +======= + +.. The sitemap.html template will insert here the page tree automatically. diff --git a/Documentation/guides.xml b/Documentation/guides.xml index 7f85bd3..71f1289 100644 --- a/Documentation/guides.xml +++ b/Documentation/guides.xml @@ -13,8 +13,8 @@ typo3-core-preferred="stable" />