Browse Source

Add documentation

Add detailed documentation rendered at docs.typo3.org beside existing
readme.

Resolves: #20
pull/33/head
Daniel Siepmann 1 year ago
parent
commit
eac551e2bc
  1. 59
      Documentation/Configuration.rst
  2. 53
      Documentation/Features.rst
  3. BIN
      Documentation/Images/BE-Module-Imports.png
  4. BIN
      Documentation/Images/BE-Module-Overview.png
  5. 9
      Documentation/Includes.txt
  6. 22
      Documentation/Index.rst
  7. 24
      Documentation/Installation.rst
  8. 16
      Documentation/Introduction/Index.rst
  9. 52
      Documentation/Settings.cfg
  10. 9
      Documentation/Sitemap.rst
  11. 2
      README.md
  12. 5
      composer.json

59
Documentation/Configuration.rst

@ -0,0 +1,59 @@
.. include:: Includes.txt
.. _configuration:
=============
Configuration
=============
.. _api-key:
API Key
-------
Some API requests are only possible by providing an API Key.
This key can be configured via "Extension Configuration".
.. _storage-pids:
Storage Pids
------------
The configuration of imports is stored within TYPO3 records.
Those records can be created via backend module.
Each new record is stored on a default page. The default is ``0``.
That would prevent editors from creating and editing records.
This page uid can be configured via TypoScript::
module {
tx_thuecat {
settings {
newRecordPid {
tx_thuecat_import_configuration = 10
}
}
}
}
.. _import-configuration:
Import configuration
--------------------
Each import is defined via a special import configuration record.
This record can be created via TYPO3 backend module.
There are different configurations available:
Static list of URLs
Allows to define a list of URLs which should be imported.
These URLs should reference a single resource to import without any given parameters like a format.
Synchronization area
Allows to import a so called "Synchronisationsbereich".
Find out more at https://cms.thuecat.org/developer.
Add the given ``syncScopeId`` to the configuration to update the given resources
for that specific sync scope.
This requires an configured :ref:`api-key`.
All configurations also provide an input to define the page where records should be
stored and updated.

53
Documentation/Features.rst

@ -0,0 +1,53 @@
.. _features:
========
Features
========
* Support multiple languages.
Import
======
Import of specific resources via static URLs.
This allows import of specific tourist attractions and towns.
* The following data types can be imported (not all properties are supported):
* Organisations (responsible for content)
* Towns
* Tourist information
* Tourist attraction
Backend module
==============
Allows to create new import configurations.
Allows to inspect:
* Current existing organisations and their towns and tourist information
* Existing import configuration
* past imports and possible errors, as well as number of affected records.
.. figure:: /Images/BE-Module-Overview.png
:align: center
Figure 1-1: Overview of currently available configurations and Organisations.
.. figure:: /Images/BE-Module-Imports.png
:align: center
Figure 1-2: Overview of executed imports and their results.
Frontend
========
A dedicated content element is provided to display tourist attraction.
A dedicated Page Type is provided to reference tourist attraction.

BIN
Documentation/Images/BE-Module-Imports.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

BIN
Documentation/Images/BE-Module-Overview.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

9
Documentation/Includes.txt

@ -0,0 +1,9 @@
.. role:: html(code)
.. role:: typoscript(code)
.. role:: ts(typoscript)
:class: typoscript
.. role:: php(code)
.. role:: yaml(code)
.. default-role:: typoscript
.. highlight:: typoscript

22
Documentation/Index.rst

@ -0,0 +1,22 @@
.. _start:
===========
EXT:thuecat
===========
ThüCAT is ¨Thüringer Content Architektur Tourismus¨.
This is an extension for TYPO3 CMS (https://typo3.org/) to integrate ThüCAT.
The existing API is integrated and allows importing data into the system.
Table of Contents
=================
.. toctree::
:maxdepth: 2
:titlesonly:
:glob:
Features
Installation
Configuration
Sitemap

24
Documentation/Installation.rst

@ -0,0 +1,24 @@
.. _installation:
============
Installation
============
The extension can be installed via composer,
see `the package at packagist.org <https://packagist.org/packages/werkraummedia/thuecat>`_.
Further info is available at :ref:`t3install:install-extension-with-composer` from
TYPO3 installation guide.
The extension can be installed via file system.
Download the corresponding version `at GitHub <https://github.com/werkraum-media/thuecat/releases>`_.
Unpack into :file:`typo3conf/ext/`.
The extension needs to be activated via the "Extension Manager".
See :ref:`t3gettingstarted:extension-manager`.
Integrators can include and configure TypoScript once it is installed and enabled.
See :ref:`t3tsref:static-includes`.
All available configurations can be found at :ref:`configuration`.
At least one import configuration needs to be created and imported.
See :ref:`import-configuration`.

16
Documentation/Introduction/Index.rst

@ -0,0 +1,16 @@
.. include:: ../Includes.txt
.. _introduction:
==============
Introduction
==============
.. _what-it-does:
What does it do?
================
This TYPO3 extension is an example of best practices in continuous integration and automated code checks, also
writing unit and functional tests with PHPUnit in Extbase/Fluid-based extensions for TYPO3 CMS, and then running them
in a pipeline.

52
Documentation/Settings.cfg

@ -0,0 +1,52 @@
[general]
# .................................................................................
# ... (required) title (displayed in left sidebar (desktop) or top panel (mobile)
# .................................................................................
project = TYPO3 EXT:thuecat
# .................................................................................
# ... (recommended) version, displayed next to title (desktop) and in <meta name="book-version"
# .................................................................................
release = latest
# .................................................................................
# ... (recommended) displayed in footer
# .................................................................................
copyright = 2020 by werkraum-media
[html_theme_options]
# .................................................................................
# ... (recommended) to get the "Edit me on Github Button"
# .................................................................................
github_branch = main
github_repository = werkraum-media/thuecat
# usually an email address
project_contact = coding@daniel-siepmann.de
# URL of online discussions, you can leave this blank
project_discussions =
# URL of webpage of your extension (if it has one)
project_home = https://github.com/werkraum-media/thuecat
# URL to Issues
project_issues = https://github.com/werkraum-media/thuecat/issues
# URL of repository
project_repository = https://github.com/werkraum-media/thuecat
[intersphinx_mapping]
# .................................................................................
# for cross-referencing across manuals (intersphinx) with :ref:
# You must uncomment all manuals you use in your cross-references
#
# Example usage:
# :ref:`t3contribute:start` will link to start page of Contribution Guide
# .................................................................................
t3install = https://docs.typo3.org/m/typo3/guide-installation/master/en-us/
t3gettingstarted = https://docs.typo3.org/m/typo3/tutorial-getting-started/master/en-us/
t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/

9
Documentation/Sitemap.rst

@ -0,0 +1,9 @@
:template: sitemap.html
.. _sitemap:
=======
Sitemap
=======
.. template 'sitemap.html' will insert the toctree as a sitemap here below normal contents

2
README.md

@ -4,6 +4,8 @@ ThüCAT is ¨Thüringer Content Architektur Tourismus¨.
This is an extension for TYPO3 CMS (https://typo3.org/) to integrate ThüCAT.
The existing API is integrated and allows importing data into the system.
Full documentation available at https://docs.typo3.org/p/werkraummedia/thuecat/master/en-us/.
## Current state
The extension already allows:

5
composer.json

@ -5,9 +5,10 @@
"license": "GPL-2.0-or-later",
"homepage": "https://github.com/werkraum-media/thuecat",
"support": {
"docs": "https://docs.typo3.org/p/werkraummedia/thuecat/master/en-us/",
"email": "coding@daniel-siepmann.de",
"source": "https://github.com/werkraum-media/thuecat",
"issues": "https://github.com/werkraum-media/thuecat/issues"
"issues": "https://github.com/werkraum-media/thuecat/issues",
"source": "https://github.com/werkraum-media/thuecat"
},
"authors": [
{

Loading…
Cancel
Save