[DOCS] Add basic documentation structure

.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<<EOF'
+            echo "https://github.com/${{ github.repository }}/releases/tag/${{ env.version }}"
+            echo EOF
+          } >> "$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

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 <extensionConfiguration>`
+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

Documentation/Administration/Index.rst

@@ -0,0 +1,14 @@
+..  include:: /Includes.rst.txt
+
+..  _administration:
+
+==============
+Administration
+==============
+
+..  toctree::
+    :maxdepth: 5
+    :titlesonly:
+
+    Installation/Index
+    Configuration/Index

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 <configuration>`
+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

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"
+
+

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

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 <http://www.typo3.org/>`_.
+
+**Table of Contents**
+
+..  toctree::
+    :maxdepth: 5
+    :titlesonly:
+    :glob:
+
+    Introduction/Index
+    Administration/Index
+    Reference/Index
+    KnownIssues/Index

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`.

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 <https://docs.typo3.org/p/web-vision/deepl-write/main/en-us/>`__.
+
+Contribution workflow
+---------------------
+
+#.  Please always create an issue on `Github <https://github.com/web-vision/deepl-write/issues>`__
+    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.

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

Documentation/Introduction/Sponsoring/Index.rst

@@ -0,0 +1,8 @@
+
+..  _sponsoring:
+
+Sponsors
+========
+
+No sponsoring for DeepL Write integration yet.
+

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 <Contribution>`.

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

Documentation/Reference/Index.rst

@@ -0,0 +1,10 @@
+..  _reference:
+
+Reference
+=========
+
+..  toctree::
+    :maxdepth: 3
+    :titlesonly:
+
+    ExtensionConfiguration/Index

Documentation/guides.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+        links-are-relative="true"
+>
+    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+               project-home="https://github.com/web-vision/deepl-write"
+               project-contact="hello@web-vision.de"
+               project-repository="https://github.com/web-vision/deepl-write"
+               project-issues="https://github.com/web-vision/deepl-write/issues"
+               edit-on-github-branch="main"
+               edit-on-github="web-vision/deepl-write"
+               typo3-core-preferred="stable"
+    />
+    <project title="DeepL Write"
+             release="main (development)"
+             version="main (development)"
+             copyright="since 2025 by web-vision GmbH &amp; Contributors"
+    />
+</guides>