Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FEATURE] Switch to PHP-based documentation rendering #318

Merged
merged 6 commits into from
Mar 12, 2024
Merged

[FEATURE] Switch to PHP-based documentation rendering #318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0acaa1c
[FEATURE] Switch to PHP-based documentation rendering
linawolf Mar 2, 2024
bdbbd5e
[BUGFIX] Resolve documentation warnings and errors
linawolf Mar 2, 2024
f0110e8
[TASK] Add automatic tests for Documentation
linawolf Mar 2, 2024
458c61b
[TASK] Modernize rst includes
linawolf Mar 2, 2024
14aab33
[DOCS] Fix method signature
linawolf Mar 2, 2024
bad0393
[DOCS] Fix guides.xml
linawolf Mar 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/documentation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/Documentation-GENERATED-temp/
15 changes: 15 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion Documentation/.editorconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Documentation/Administration/AdditionalFields/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. include:: ../../Includes.txt
.. include:: /Includes.rst.txt


.. _administration-additionalfields:
Expand Down
2 changes: 1 addition & 1 deletion Documentation/Administration/ArrayPath/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. include:: ../../Includes.txt
.. include:: /Includes.rst.txt


.. _administration-array-path:
Expand Down
2 changes: 1 addition & 1 deletion Documentation/Administration/Children/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. include:: ../../Includes.txt
.. include:: /Includes.rst.txt


.. _administration-children:
Expand Down
162 changes: 81 additions & 81 deletions Documentation/Administration/Columns/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. include:: ../../Includes.txt
.. include:: /Includes.rst.txt


.. _administration-columns:
Expand All @@ -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.

Expand Down Expand Up @@ -244,29 +244,29 @@ Description

.. code-block:: xml

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
<InvoiceLine>
<cbc:ID>A1</cbc:ID>
<cbc:LineExtensionAmount currencyID="USD">100.00</cbc:LineExtensionAmount>
<cac:OrderReference>
<cbc:ID>000001</cbc:ID>
</cac:OrderReference>
</InvoiceLine>
...
</Invoice>
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
<InvoiceLine>
<cbc:ID>A1</cbc:ID>
<cbc:LineExtensionAmount currencyID="USD">100.00</cbc:LineExtensionAmount>
<cac:OrderReference>
<cbc:ID>000001</cbc:ID>
</cac:OrderReference>
</InvoiceLine>
...
</Invoice>

getting the value in the :code:`<cbc:LineExtensionAmount>` 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)
Expand Down Expand Up @@ -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' => [
Expand All @@ -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:
Expand Down Expand Up @@ -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' => [
Expand All @@ -533,7 +533,7 @@ Description
]
]
]
];
];

The "userFunction" will be executed first (:code:`10`) and the "trim" next (:code:`20`).

Expand Down
8 changes: 4 additions & 4 deletions Documentation/Administration/GeneralTca/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. include:: ../../Includes.txt
.. include:: /Includes.rst.txt


.. _administration-general-tca:
Expand All @@ -13,7 +13,7 @@ The same keys need to be used again in the :ref:`column configuration <administr

.. code-block:: php

$GLOBALS['TCA']['tx_externalimporttest_tag'] = array_merge_recursive( $GLOBALS['TCA']['tx_externalimporttest_tag'], [
$GLOBALS['TCA']['tx_externalimporttest_tag'] = array_merge_recursive( $GLOBALS['TCA']['tx_externalimporttest_tag'], [
'external' => [
'general' => [
0 => [
Expand All @@ -37,7 +37,7 @@ The same keys need to be used again in the :ref:`column configuration <administr
]
]
],
]);
]);


All available properties are described below.
Expand Down Expand Up @@ -244,7 +244,7 @@ Type
bool

Description
When the special :code:`*` segment is used in an :ref:`arrayPath <administration-general-tca-properties-array-path>`,
When the special :code:`*` segment is used in an :ref:`arrayPath <administration-general-tca-properties-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.
Expand Down
4 changes: 2 additions & 2 deletions Documentation/Administration/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. include:: ../Includes.txt
.. include:: /Includes.rst.txt


.. _import-configuration:
Expand All @@ -23,7 +23,7 @@ understand which part of the process it impacts. The names of the
steps correspond to the :ref:`process steps <user-overview>`.

There are some code examples throughout this chapter. They are
taken either from the :ref:`External Import Tutorial <tut:start>`
taken either from the :ref:`External Import Tutorial <cobweb/externalimport_tut:start>`
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).
Expand Down
2 changes: 1 addition & 1 deletion Documentation/Administration/LogCleanup/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. include:: ../../Includes.txt
.. include:: /Includes.rst.txt


.. _administration-log-cleanup:
Expand Down
Loading