From 4d554f4276680e1ef4c4773d7e44e0052581c2e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20B=C3=BCrk?= Date: Thu, 18 Dec 2025 15:47:52 +0100 Subject: [PATCH] [DOCS] Add basic documentation structure This change adds a first basic documentation to the repository containing at least installation and contribution guide. --- .github/workflows/publish.yml | 27 ++++++++--- .../Administration/Configuration/Index.rst | 42 +++++++++++++++++ Documentation/Administration/Index.rst | 14 ++++++ .../Administration/Installation/Index.rst | 41 +++++++++++++++++ Documentation/Files/versionSupport.csv | 4 ++ Documentation/Includes.rst.txt | 34 ++++++++++++++ Documentation/Index.rst | 45 +++++++++++++++++++ Documentation/Introduction/About/Index.rst | 12 +++++ .../Introduction/Contribution/Index.rst | 30 +++++++++++++ Documentation/Introduction/Index.rst | 15 +++++++ .../Introduction/Sponsoring/Index.rst | 8 ++++ Documentation/KnownIssues/Index.rst | 8 ++++ .../ExtensionConfiguration/Index.rst | 38 ++++++++++++++++ Documentation/Reference/Index.rst | 10 +++++ Documentation/guides.xml | 21 +++++++++ README.md | 28 +++++++----- 16 files changed, 361 insertions(+), 16 deletions(-) create mode 100644 Documentation/Administration/Configuration/Index.rst create mode 100644 Documentation/Administration/Index.rst create mode 100644 Documentation/Administration/Installation/Index.rst create mode 100644 Documentation/Files/versionSupport.csv create mode 100644 Documentation/Includes.rst.txt create mode 100644 Documentation/Index.rst create mode 100644 Documentation/Introduction/About/Index.rst create mode 100644 Documentation/Introduction/Contribution/Index.rst create mode 100644 Documentation/Introduction/Index.rst create mode 100644 Documentation/Introduction/Sponsoring/Index.rst create mode 100644 Documentation/KnownIssues/Index.rst create mode 100644 Documentation/Reference/ExtensionConfiguration/Index.rst create mode 100644 Documentation/Reference/Index.rst create mode 100644 Documentation/guides.xml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 68791b5..123473f 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -33,6 +33,15 @@ jobs: run: | echo "DETECTED_EXTENSION_KEY=$(cat composer.json | jq -r '.extra."typo3/cms"."extension-key"' )" >> "$GITHUB_ENV" + - name: Get comment + id: get-comment + run: | + { + echo 'terReleaseNotes<> "$GITHUB_ENV" + - name: Setup PHP 8.1 if: github.event.base_ref == 'refs/heads/main' uses: shivammathur/setup-php@v2 @@ -52,6 +61,13 @@ jobs: run: | php ~/.composer/vendor/bin/tailor create-artefact ${{ env.version }} ${{ env.DETECTED_EXTENSION_KEY }} + - name: "Render documentation" + run: | + Build/Scripts/runTests.sh -s renderDocumentation && \ + mkdir -p tailor-version-artefact && \ + cd Documentation-GENERATED-temp && \ + zip -r ../tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}-documentation.zip + # Note that when release already exists for tag, only files will be uploaded and lets this acting as a # fallback to ensure that a real GitHub release is created for the tag along with extension artifacts. - name: Create release and upload artifacts in the same step @@ -65,12 +81,11 @@ jobs: generate_release_notes: true files: | tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}.zip + tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}-documentation.zip LICENSE fail_on_unmatched_files: true -# @todo No public TER release yet. TER Upload package uploaded to GitHub release(s) can be used to -# upload versions later to TER manually when making extension public. -# - name: Publish to TER -# run: | -# php ~/.composer/vendor/bin/tailor ter:publish --comment "${{ env.terReleaseNotes }}" ${{ env.version }} \ -# --artefact=tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}.zip + - name: Publish to TER + run: | + php ~/.composer/vendor/bin/tailor ter:publish --comment "${{ env.terReleaseNotes }}" ${{ env.version }} \ + --artefact=tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}.zip diff --git a/Documentation/Administration/Configuration/Index.rst b/Documentation/Administration/Configuration/Index.rst new file mode 100644 index 0000000..2b65e48 --- /dev/null +++ b/Documentation/Administration/Configuration/Index.rst @@ -0,0 +1,42 @@ +.. include:: /Includes.rst.txt + +.. _configuration: + +Configuration +============= + +Set up DeepL API (PRO) key +-------------------------- + +.. attention:: + + Before using the DeepL API, you need to get an API key from your `DeepL Profile`_. + +Go to the :ref:`extension configuration ` +in :guilabel:`Admin Tools > Settings > Extension Configuration`. + +Open the settings for :guilabel:`deepl_write` and add your API key. + +.. attention:: + + Be aware that based on `DeepL Write API` requirements a paid `DeepL PRO` + api key is required for this extension, which can also be used for the + `deepltranslate-core` or using there a free key. + +.. _sitesetup: + +Set up translation language +--------------------------- + +.. attention:: + + Be aware that the DeepL Write API only supports a subset of languages for + now and is hardcoded in the extension due to a missing API endpoint. + +#. Go to :guilabel:`Site Management > Sites` and edit your site configuration + +#. Switch to tab `Languages` and open your target + +#. Go to :guilabel:`DeepL Settings` and set up your `DeepL Write language` + +.. _DeepL Profile: https://www.deepl.com/en/your-account/keys diff --git a/Documentation/Administration/Index.rst b/Documentation/Administration/Index.rst new file mode 100644 index 0000000..7474eca --- /dev/null +++ b/Documentation/Administration/Index.rst @@ -0,0 +1,14 @@ +.. include:: /Includes.rst.txt + +.. _administration: + +============== +Administration +============== + +.. toctree:: + :maxdepth: 5 + :titlesonly: + + Installation/Index + Configuration/Index diff --git a/Documentation/Administration/Installation/Index.rst b/Documentation/Administration/Installation/Index.rst new file mode 100644 index 0000000..f8bae13 --- /dev/null +++ b/Documentation/Administration/Installation/Index.rst @@ -0,0 +1,41 @@ +.. include:: /Includes.rst.txt + +.. _installation: + +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 + + .. code-block:: bash + + composer require -W 'web-vision/deepl-write':'^1.0' + + in your TYPO3 installation. + +#. **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. + +#. **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. + +The extension then needs to be :ref:`configured ` +in order to display translation buttons in the desired languages. + +.. _TER: https://extensions.typo3.org/extension/deepl_write + +Compatibility +------------- + +DeepL Write supports: + +.. csv-table:: Changes + :header: "DeepL Write version","TYPO3 Version","PHP version(s)","Supported" + :file: Files/versionSupport.csv diff --git a/Documentation/Files/versionSupport.csv b/Documentation/Files/versionSupport.csv new file mode 100644 index 0000000..88becb6 --- /dev/null +++ b/Documentation/Files/versionSupport.csv @@ -0,0 +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" + + diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt new file mode 100644 index 0000000..210ac57 --- /dev/null +++ b/Documentation/Includes.rst.txt @@ -0,0 +1,34 @@ +.. 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 new file mode 100644 index 0000000..48362c6 --- /dev/null +++ b/Documentation/Index.rst @@ -0,0 +1,45 @@ +.. include:: /Includes.rst.txt + +========================= + DeepL Write +========================= + +:Extension key: + deepl_write + +:Package name: + web-vision/deepl-write + +:Version: + |release| + +:Language: + en + +:Copyright: + 2024 + +:Author: + web-vision GmbH + +:Rendered: + |today| + +:License: + This document is published under the Open Content License + available from http://www.opencontent.org/opl.shtml + + The content of this document is related to TYPO3, + a GNU/GPL CMS/Framework available from `www.typo3.org `_. + +**Table of Contents** + +.. toctree:: + :maxdepth: 5 + :titlesonly: + :glob: + + Introduction/Index + Administration/Index + Reference/Index + KnownIssues/Index diff --git a/Documentation/Introduction/About/Index.rst b/Documentation/Introduction/About/Index.rst new file mode 100644 index 0000000..6f2df5f --- /dev/null +++ b/Documentation/Introduction/About/Index.rst @@ -0,0 +1,12 @@ +.. include:: /Includes.rst.txt + +.. _whatDoesItDo: + +What does it do? +================ + +This extension provides the ability to use DeepL Write for RTE fields +to make translations and switching between different formalities of +languages. + +Install via :composer:`web-vision/deepl-write` or :t3ext:`deepl_write`. diff --git a/Documentation/Introduction/Contribution/Index.rst b/Documentation/Introduction/Contribution/Index.rst new file mode 100644 index 0000000..03890da --- /dev/null +++ b/Documentation/Introduction/Contribution/Index.rst @@ -0,0 +1,30 @@ +.. include:: /Includes.rst.txt + +.. _contribution: + +Contribution +============ + +Contributions are essential to the success of open source projects, but they are by no means +limited to contributing code. Much more can be done, for example by +improving the `documentation `__. + +Contribution workflow +--------------------- + +#. Please always create an issue on `Github `__ + before starting a change. This is very helpful to understand what kind of + problem the pull request solves, and whether your change will be accepted. + +#. Bug fixes: Please describe the nature of the bug you wish to report and + provide how to reproduce the problem. We will only accept bug fixes if + we can can reproduce the problem. + +#. Features: Not every feature is relevant to the majority of users. + In addition: We do not want to complicate the usability of this extension + for a marginal feature. It helps to have a discussion about a new feature + before opening a pull request. + +#. Please always create a pull request based on the updated release branch. + This ensures that the necessary quality checks and tests are performed as + a quality can be performed. diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst new file mode 100644 index 0000000..2bbd9da --- /dev/null +++ b/Documentation/Introduction/Index.rst @@ -0,0 +1,15 @@ +.. _introduction: + +Introduction +============ + +This chapter gives you a basic introduction about the TYPO3 CMS extension +"*deepl_write*". + +.. toctree:: + :maxdepth: 5 + :titlesonly: + + About/Index + Contribution/Index + Sponsoring/Index diff --git a/Documentation/Introduction/Sponsoring/Index.rst b/Documentation/Introduction/Sponsoring/Index.rst new file mode 100644 index 0000000..bdde3d0 --- /dev/null +++ b/Documentation/Introduction/Sponsoring/Index.rst @@ -0,0 +1,8 @@ + +.. _sponsoring: + +Sponsors +======== + +No sponsoring for DeepL Write integration yet. + diff --git a/Documentation/KnownIssues/Index.rst b/Documentation/KnownIssues/Index.rst new file mode 100644 index 0000000..8ed89b5 --- /dev/null +++ b/Documentation/KnownIssues/Index.rst @@ -0,0 +1,8 @@ +.. include:: /Includes.rst.txt + +.. _knownissues: + +Known Issues +============ + +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 new file mode 100644 index 0000000..af99ee1 --- /dev/null +++ b/Documentation/Reference/ExtensionConfiguration/Index.rst @@ -0,0 +1,38 @@ +.. include:: /Includes.rst.txt + +.. _extensionConfiguration: + +======================= +Extension Configuration +======================= + +Some general settings must be configured in the Extension Configuration. + +#. Go to :guilabel:`Admin Tools > Settings > Extension Configuration` +#. Choose :guilabel:`deepl_write` + +.. attention:: + + Before using the DeepL API (PRO), you need to get an API key from your `DeepL Profile`_. + +.. _deeplApiKey: + +DeepL API Key +============= + +.. attention:: + + Be aware that based on `DeepL Write API` requirements a paid `DeepL PRO` + api key is required for this extension, which can also be used for the + `deepltranslate-core` or using there a free key. + +.. confval:: apiKey + + :type: string + + Add your DeepL API (PRO) Key here. + + +.. _DeepL Free API: https://www.deepl.com/pro-checkout/account?productId=1200&yearly=false&trial=false +.. _DeepL Profile: https://www.deepl.com/en/your-account/keys +.. _DeepL Pro: https://www.deepl.com/de/pro diff --git a/Documentation/Reference/Index.rst b/Documentation/Reference/Index.rst new file mode 100644 index 0000000..af303fc --- /dev/null +++ b/Documentation/Reference/Index.rst @@ -0,0 +1,10 @@ +.. _reference: + +Reference +========= + +.. toctree:: + :maxdepth: 3 + :titlesonly: + + ExtensionConfiguration/Index diff --git a/Documentation/guides.xml b/Documentation/guides.xml new file mode 100644 index 0000000..1265a39 --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,21 @@ + + + + + diff --git a/README.md b/README.md index 6020203..2a7123d 100644 --- a/README.md +++ b/README.md @@ -3,19 +3,20 @@ TYPO3 extension for DeepL Write integration. Write better texts > [!IMPORTANT] -> This is a development preview. Please use it at your own risk. +> This extension is still in a early development phase and still +> considered unstable and releases as beta version. -| | URL | -|------------------|----------------------------------------------| -| **Repository:** | https://github.com/web-vision/deepl-write | -| **Read online:** | - | -| **TER:** | - | +| | URL | +|------------------|-------------------------------------------------------------| +| **Repository:** | https://github.com/web-vision/deepl-write | +| **Read online:** | https://docs.typo3.org/p/web-vision/deepl-write/main/en-us/ | +| **TER:** | https://extensions.typo3.org/extension/deepl_write/ | ## Compatibility -| Branch | Version | TYPO3 | PHP | -|--------|---------|-----------|---------------------------------------------------| -| main | 1.x-dev | v12 + v13 | 8.1, 8.2, 8.3, 8.4 (depending on TYPO3) | +| Branch | Version | TYPO3 | PHP | +|--------|---------|-----------|----------------------------------------------| +| main | 1.x-dev | v12 + v13 | 8.1, 8.2, 8.3, 8.4, 8.5 (depending on TYPO3) | ## Installation @@ -27,10 +28,17 @@ Install with your flavour: We prefer composer installation: ```bash -composer config repositories."deepl-write" vcs web-vision/deepl-write && \ composer require -W 'web-vision/deepl-write':'^1.0' ``` +In case you had a repository configured from early EAP phase, the repository +can be removed: + +```bash +composer config --unset repositories."deepl-write" && \ + composer update --lock +``` + ## Configuration `EXT:deepl_write` can be used standalone or in cooperation with established