Skip to content

Commit 4d554f4

Browse files
sbuerksbuerk
committed
[DOCS] Add basic documentation structure
This change adds a first basic documentation to the repository containing at least installation and contribution guide.
1 parent e717b62 commit 4d554f4

16 files changed

Lines changed: 361 additions & 16 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,15 @@ jobs:
3333
run: |
3434
echo "DETECTED_EXTENSION_KEY=$(cat composer.json | jq -r '.extra."typo3/cms"."extension-key"' )" >> "$GITHUB_ENV"
3535
36+
- name: Get comment
37+
id: get-comment
38+
run: |
39+
{
40+
echo 'terReleaseNotes<<EOF'
41+
echo "https://github.com/${{ github.repository }}/releases/tag/${{ env.version }}"
42+
echo EOF
43+
} >> "$GITHUB_ENV"
44+
3645
- name: Setup PHP 8.1
3746
if: github.event.base_ref == 'refs/heads/main'
3847
uses: shivammathur/setup-php@v2
@@ -52,6 +61,13 @@ jobs:
5261
run: |
5362
php ~/.composer/vendor/bin/tailor create-artefact ${{ env.version }} ${{ env.DETECTED_EXTENSION_KEY }}
5463
64+
- name: "Render documentation"
65+
run: |
66+
Build/Scripts/runTests.sh -s renderDocumentation && \
67+
mkdir -p tailor-version-artefact && \
68+
cd Documentation-GENERATED-temp && \
69+
zip -r ../tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}-documentation.zip
70+
5571
# Note that when release already exists for tag, only files will be uploaded and lets this acting as a
5672
# fallback to ensure that a real GitHub release is created for the tag along with extension artifacts.
5773
- name: Create release and upload artifacts in the same step
@@ -65,12 +81,11 @@ jobs:
6581
generate_release_notes: true
6682
files: |
6783
tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}.zip
84+
tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}-documentation.zip
6885
LICENSE
6986
fail_on_unmatched_files: true
7087

71-
# @todo No public TER release yet. TER Upload package uploaded to GitHub release(s) can be used to
72-
# upload versions later to TER manually when making extension public.
73-
# - name: Publish to TER
74-
# run: |
75-
# php ~/.composer/vendor/bin/tailor ter:publish --comment "${{ env.terReleaseNotes }}" ${{ env.version }} \
76-
# --artefact=tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}.zip
88+
- name: Publish to TER
89+
run: |
90+
php ~/.composer/vendor/bin/tailor ter:publish --comment "${{ env.terReleaseNotes }}" ${{ env.version }} \
91+
--artefact=tailor-version-artefact/${{ env.DETECTED_EXTENSION_KEY }}_${{ env.version }}.zip

‎Documentation/Administration/Configuration/Index.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _configuration:
4+
5+
Configuration
6+
=============
7+
8+
Set up DeepL API (PRO) key
9+
--------------------------
10+
11+
.. attention::
12+
13+
Before using the DeepL API, you need to get an API key from your `DeepL Profile`_.
14+
15+
Go to the :ref:`extension configuration <extensionConfiguration>`
16+
in :guilabel:`Admin Tools > Settings > Extension Configuration`.
17+
18+
Open the settings for :guilabel:`deepl_write` and add your API key.
19+
20+
.. attention::
21+
22+
Be aware that based on `DeepL Write API` requirements a paid `DeepL PRO`
23+
api key is required for this extension, which can also be used for the
24+
`deepltranslate-core` or using there a free key.
25+
26+
.. _sitesetup:
27+
28+
Set up translation language
29+
---------------------------
30+
31+
.. attention::
32+
33+
Be aware that the DeepL Write API only supports a subset of languages for
34+
now and is hardcoded in the extension due to a missing API endpoint.
35+
36+
#. Go to :guilabel:`Site Management > Sites` and edit your site configuration
37+
38+
#. Switch to tab `Languages` and open your target
39+
40+
#. Go to :guilabel:`DeepL Settings` and set up your `DeepL Write language`
41+
42+
.. _DeepL Profile: https://www.deepl.com/en/your-account/keys

‎Documentation/Administration/Index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _administration:
4+
5+
==============
6+
Administration
7+
==============
8+
9+
.. toctree::
10+
:maxdepth: 5
11+
:titlesonly:
12+
13+
Installation/Index
14+
Configuration/Index

‎Documentation/Administration/Installation/Index.rst‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _installation:
4+
5+
Installation
6+
============
7+
8+
The extension has to be installed like any other TYPO3 CMS extension.
9+
You can download the extension using one of the following methods:
10+
11+
#. **Use composer**:
12+
Run
13+
14+
.. code-block:: bash
15+
16+
composer require -W 'web-vision/deepl-write':'^1.0'
17+
18+
in your TYPO3 installation.
19+
20+
#. **Get it from the Extension Manager**:
21+
Switch to the module :guilabel:`Admin Tools > Extensions`.
22+
Switch to :guilabel:`Get Extensions` and search for the extension key
23+
*deepltranslate_core* and import the extension from the repository.
24+
25+
#. **Get it from typo3.org**:
26+
You can always get current version from `TER`_ by downloading the zip
27+
version. Upload the file afterwards in the Extension Manager.
28+
29+
The extension then needs to be :ref:`configured <configuration>`
30+
in order to display translation buttons in the desired languages.
31+
32+
.. _TER: https://extensions.typo3.org/extension/deepl_write
33+
34+
Compatibility
35+
-------------
36+
37+
DeepL Write supports:
38+
39+
.. csv-table:: Changes
40+
:header: "DeepL Write version","TYPO3 Version","PHP version(s)","Supported"
41+
:file: Files/versionSupport.csv

‎Documentation/Files/versionSupport.csv‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
"1.x.x","13","8.2, 8.3, 8.4, 8.5","yes"
2+
"1.x.x","12","8.1, 8.2, 8.3, 8.4","yes"
3+
4+

‎Documentation/Includes.rst.txt‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.. More information about this file:
2+
https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt
3+
4+
.. ----------
5+
.. text roles
6+
.. ----------
7+
8+
.. role:: aspect(emphasis)
9+
.. role:: bash(code)
10+
.. role:: html(code)
11+
.. role:: js(code)
12+
.. role:: php(code)
13+
.. role:: rst(code)
14+
.. role:: sep(strong)
15+
.. role:: sql(code)
16+
17+
.. role:: tsconfig(code)
18+
:class: typoscript
19+
20+
.. role:: typoscript(code)
21+
.. role:: xml(code)
22+
:class: html
23+
24+
.. role:: yaml(code)
25+
26+
.. default-role:: code
27+
28+
.. ---------
29+
.. highlight
30+
.. ---------
31+
32+
.. By default, code blocks use PHP syntax highlighting
33+
34+
.. highlight:: php

‎Documentation/Index.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. include:: /Includes.rst.txt
2+
3+
=========================
4+
DeepL Write
5+
=========================
6+
7+
:Extension key:
8+
deepl_write
9+
10+
:Package name:
11+
web-vision/deepl-write
12+
13+
:Version:
14+
|release|
15+
16+
:Language:
17+
en
18+
19+
:Copyright:
20+
2024
21+
22+
:Author:
23+
web-vision GmbH
24+
25+
:Rendered:
26+
|today|
27+
28+
:License:
29+
This document is published under the Open Content License
30+
available from http://www.opencontent.org/opl.shtml
31+
32+
The content of this document is related to TYPO3,
33+
a GNU/GPL CMS/Framework available from `www.typo3.org <http://www.typo3.org/>`_.
34+
35+
**Table of Contents**
36+
37+
.. toctree::
38+
:maxdepth: 5
39+
:titlesonly:
40+
:glob:
41+
42+
Introduction/Index
43+
Administration/Index
44+
Reference/Index
45+
KnownIssues/Index

‎Documentation/Introduction/About/Index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _whatDoesItDo:
4+
5+
What does it do?
6+
================
7+
8+
This extension provides the ability to use DeepL Write for RTE fields
9+
to make translations and switching between different formalities of
10+
languages.
11+
12+
Install via :composer:`web-vision/deepl-write` or :t3ext:`deepl_write`.

‎Documentation/Introduction/Contribution/Index.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _contribution:
4+
5+
Contribution
6+
============
7+
8+
Contributions are essential to the success of open source projects, but they are by no means
9+
limited to contributing code. Much more can be done, for example by
10+
improving the `documentation <https://docs.typo3.org/p/web-vision/deepl-write/main/en-us/>`__.
11+
12+
Contribution workflow
13+
---------------------
14+
15+
#. Please always create an issue on `Github <https://github.com/web-vision/deepl-write/issues>`__
16+
before starting a change. This is very helpful to understand what kind of
17+
problem the pull request solves, and whether your change will be accepted.
18+
19+
#. Bug fixes: Please describe the nature of the bug you wish to report and
20+
provide how to reproduce the problem. We will only accept bug fixes if
21+
we can can reproduce the problem.
22+
23+
#. Features: Not every feature is relevant to the majority of users.
24+
In addition: We do not want to complicate the usability of this extension
25+
for a marginal feature. It helps to have a discussion about a new feature
26+
before opening a pull request.
27+
28+
#. Please always create a pull request based on the updated release branch.
29+
This ensures that the necessary quality checks and tests are performed as
30+
a quality can be performed.

‎Documentation/Introduction/Index.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. _introduction:
2+
3+
Introduction
4+
============
5+
6+
This chapter gives you a basic introduction about the TYPO3 CMS extension
7+
"*deepl_write*".
8+
9+
.. toctree::
10+
:maxdepth: 5
11+
:titlesonly:
12+
13+
About/Index
14+
Contribution/Index
15+
Sponsoring/Index

0 commit comments

Comments
 (0)