[TASK] Modernize documentation

astehlik · Feb 23, 2021 · 5845e37 · 5845e37
1 parent a872c76
commit 5845e37
Show file tree

Hide file tree

Showing 15 changed files with 177 additions and 208 deletions.
diff --git a/Documentation/Administrator/Index.rst b/Documentation/Administrator/Index.rst
@@ -1,10 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../Includes.txt
-
+.. include:: ../Includes.txt
 
 .. _admin-manual:
 
@@ -47,7 +41,7 @@ You can convert any typolink to a tinyurl by simply setting the property tinyurl
 
 This is a quick example:
 
-::
+.. code-block:: typoscript
 
 	page.30 = TEXT
 	page.30 {
@@ -62,8 +56,6 @@ Further information
 -------------------
 
 .. toctree::
-	:maxdepth: 5
-	:titlesonly:
-	:glob:
+   :maxdepth: 3
 
-	SpeakingUrlConfiguration/Index
+   SpeakingUrlConfiguration/Index
diff --git a/Documentation/Administrator/SpeakingUrlConfiguration/Index.rst b/Documentation/Administrator/SpeakingUrlConfiguration/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: ../Includes.txt
 
 .. _admin-speaking-url-configuration:
 
@@ -14,7 +9,9 @@ By default, a tiny URL created by this extension will look like this:
 
 `<http://mytypo3page.tld/index.php?eID=tx_tinyurls&tx_tinyurls[key ]=Aefc-3E>`_
 
-This is not very short and readable. This is why using speaking URLs is recommended. For this to work you need to set createSpeakingURLs to 1 and maybe edit the speakingUrlTemplate . By default, speaking URLs will look like this:
+This is not very short and readable. This is why using speaking URLs is recommended. For this to work you need
+to set createSpeakingURLs to 1 and maybe edit the speakingUrlTemplate . By default, speaking URLs will look
+like this:
 
 http://mytypo3page.tld/goto/Aefc-3E
 
@@ -30,7 +27,7 @@ When you are using mod_rewrite you can use this line in your .htaccess file or y
 
 ::
 
-    RewriteRule ^tinyurl/([a-zA-Z0-9]+(\-[a-zA-Z0-9]+)?)$ /index.php?eID=tx_tinyurls&tx_tinyurls[key]=$1
+    RewriteRule ^tinyurl/([a-zA-Z0-9]+(-[a-zA-Z0-9]+)?)$ /index.php?eID=tx_tinyurls&tx_tinyurls[key]=$1
 
 
 .. _admin-speaking-url-configuration-lighttpd:
@@ -46,4 +43,3 @@ When you use lighttpd you can use this configuration for rewriting tiny URLs:
         # rewrite goto urls to tinyurls extension
         "^/tinyurl/(.*)$" => typo3path + "index.php?eID=tx_tinyurls&tx_tinyurls[key]=$1",
     )
-
diff --git a/Documentation/ChangeLog/Index.rst b/Documentation/ChangeLog/Index.rst
@@ -1,16 +1,10 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../Includes.txt
-
+.. include:: ../Includes.txt
 
 .. _changelog:
 
 ChangeLog
 =========
 
-You can find the current problems, TODOs and changelogs on forge:
+You can find the current problems, TODOs and changelogs on GitHub:
 
-https://forge.typo3.org/projects/extension-tinyurls
+https://github.com/astehlik/typo3-extension-tinyurls/issues
diff --git a/Documentation/Configuration/ExtensionConfiguration/Index.rst b/Documentation/Configuration/ExtensionConfiguration/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: ../../Includes.txt
 
 .. _configuration-extension-configuration:
 
@@ -65,7 +60,7 @@ Extension configuration
          minimalRandomKeyLength
 
    Data type
-         int
+         integer
 
    Description
          The minimum length that the random part of the tiny URL must have.
@@ -79,7 +74,7 @@ Extension configuration
          minimalTinyurlKeyLength
 
    Data type
-         int
+         integer
 
    Description
          The minimum length that the whole tiny URL key must have.
@@ -93,7 +88,7 @@ Extension configuration
          urlRecordStoragePID
 
    Data type
-         int
+         integer
 
    Description
          The PID where the tiny URL records are stored, use 0 to store them in the TYPO3 root.

diff --git a/Documentation/Configuration/Index.rst b/Documentation/Configuration/Index.rst
@@ -1,10 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../Includes.txt
-
+.. include:: ../Includes.txt
 
 .. _configuration:
 
@@ -15,9 +9,7 @@ Most of the configuration is done in the extension manager. At the moment there
 few TypoScript options available.
 
 .. toctree::
-	:maxdepth: 5
-	:titlesonly:
-	:glob:
+   :maxdepth: 3
 
-	ExtensionConfiguration/Index
-	TypoScriptReference/Index
+   ExtensionConfiguration/Index
+   TypoScriptReference/Index
diff --git a/Documentation/Configuration/TypoScriptReference/Index.rst b/Documentation/Configuration/TypoScriptReference/Index.rst
@@ -1,11 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
-
-.. _configuration-typoscript:
+.. _configuration-typoscript:
 
 TypoScript Reference
 --------------------
@@ -20,7 +13,7 @@ These additional properties are available for typolink objects when the extensio
          tinyurl
 
    Data type
-         boolean
+         :ref:`t3tsref:data-type-boolean`
 
    Description
          If you set this to 1 (TRUE) the final typolink URL is converted to a tiny URL.
@@ -36,7 +29,7 @@ These additional properties are available for typolink objects when the extensio
          tinyurl.deleteOnUse
 
    Data type
-         boolean /:ref:`stdWrap <stdwrap>`
+         :ref:`t3tsref:data-type-boolean` /:ref:`t3tsref:stdWrap`
 
    Description
          If this is is true, the tiny URL is deleted from the database on the first hit.
@@ -51,7 +44,7 @@ These additional properties are available for typolink objects when the extensio
          tinyurl.validUntil
 
    Data type
-         int /:ref:`stdWrap <stdwrap>`
+         :ref:`t3tsref:data-type-integer` /:ref:`t3tsref:stdWrap`
 
    Description
          The timestamp until the URL is valid. If this is set to 0 the URL will never be invalid.
@@ -65,7 +58,7 @@ These additional properties are available for typolink objects when the extensio
          tinyurl.urlKey
 
    Data type
-         string /:ref:`stdWrap <stdwrap>`
+         :ref:`t3tsref:data-type-string` /:ref:`t3tsref:stdWrap`
 
    Description
          Normally the URL key is generated automatically. Here you can set you own unique urlKey.

diff --git a/Documentation/Developer/Index.rst b/Documentation/Developer/Index.rst
@@ -1,12 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../Includes.txt
-
-
-.. _developer:
+.. _developer:
 
 Developer Corner
 ================
@@ -17,12 +9,10 @@ Using tinyurls in your extension
 When you want to generate tiny URLs in your own extension you can use the :php:`\Tx\Tinyurls\TinyUrl\Api` class.
 Please have a look at the PHPDoc annotations for further information. This is a quick example how to use it:
 
-::
+.. code-block:: php
 
 	$tinyUrlApi = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\Tx\Tinyurls\TinyUrl\Api::class);
 	$tinyUrlApi->setDeleteOnUse(1);
 	$tinyUrlApi->setUrlKey($myKey);
 	$tinyUrlApi->setValidUntil($validUntil);
 	$myTinyUrl = $tinyUrlApi->getTinyUrl($url);
-
-
diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt
@@ -1,21 +1,17 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
+.. This is 'Includes.txt'. It is included at the very top of each and
+   every ReST source file in THIS documentation project (= manual).
 
-.. This is 'Includes.txt'. It is included at the very top of each and
-   every ReST source file in this documentation project (= manual).
+.. role:: aspect (emphasis)
+.. role:: html(code)
+.. role:: js(code)
+.. role:: php(code)
+.. role:: sep (strong)
+.. role:: sql(code)
+.. role:: typoscript(code)
+.. role:: yaml(code)
 
+.. role:: ts(typoscript)
+   :class: typoscript
 
-.. ==================================================
-.. DEFINE SOME TEXT ROLES
-.. --------------------------------------------------
-
-.. role::   typoscript(code)
-
-.. role::   ts(typoscript)
-   :class:  typoscript
-
-.. role::   php(code)
-
+.. default-role:: code
 .. highlight:: php
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -1,64 +1,39 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
+.. every .rst file should include Includes.txt
+.. use correct path!
 
 .. include:: Includes.txt
 
+.. Every manual should have a start label for cross-referencing to
+.. start page. Do not remove this!
 
 .. _start:
 
 =============================================================
-URL shortener
+URL shortener / TinyURLs
 =============================================================
 
-.. only:: html
+:Version:
+   |release|
 
-	:Classification:
-		tinyurls
+:Language:
+   en
 
-	:Version:
-		|release|
+:Author:
+   Alexander Stehlik
 
-	:Language:
-		en
+:License:
+   This extension documentation is published under the
+   `CC BY-NC-SA 4.0 <https://creativecommons.org/licenses/by-nc-sa/4.0/>`__ (Creative Commons)
+   license
 
-	:Description:
-		Manual covering TYPO3 extension URL shortener
-
-	:Keywords:
-		tinyurls,url,shortener
-
-	:Copyright:
-		2015
-
-	:Author:
-		Alexander Stehlik
-
-	:Email:
-		alexander.stehlik.deleteme@gmail.com
-
-	:License:
-		This document is published under the Open Content License
-		available from http://www.opencontent.org/opl.shtml
-
-	:Rendered:
-		|today|
-
-	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**
+This extensions allows you to cut down long URLs. It basically works like bitly or TinyURL.
 
 .. toctree::
-	:maxdepth: 5
-	:titlesonly:
-	:glob:
-
-	Introduction/Index
-	Administrator/Index
-	Configuration/Index
-	Developer/Index
-	ChangeLog/Index
-	Targets
+   :maxdepth: 3
+
+   Introduction/Index
+   Administrator/Index
+   Configuration/Index
+   Developer/Index
+   ChangeLog/Index
+   Targets
diff --git a/Documentation/Introduction/AboutTinyUrlKeys/Index.rst b/Documentation/Introduction/AboutTinyUrlKeys/Index.rst
@@ -1,12 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
-
-
-.. _introduction-about-tinyurl-keys:
+.. _introduction-about-tinyurl-keys:
 
 About Tiny URL Keys
 ===================
@@ -26,14 +18,17 @@ The first part is generated from the UID of the tiny URL database record which i
 
 The second part (after the dash) is simply a random hexadecimal string.
 
-In the extension configuration you can edit two options that influence the tiny URL key generation. If minimalTinyurlKeyLength is set the URL key must have at least this amount of characters. If the base62 part is shorter the missing characters will be appended. An example:
+In the extension configuration you can edit two options that influence the tiny URL key generation. If
+minimalTinyurlKeyLength is set the URL key must have at least this amount of characters. If the base62 part is
+shorter the missing characters will be appended. An example:
 
 * minimalTinyurlKeyLength is 6
 * the generated base62 part is Aefc
 * the URL generator will add two more characters after a dash
 * if the minimalTinyurlKeyLength was only 4 no more characters would have been added
 
-Another option is the minimalRandomKeyLength . If this is set to a value greater than zero the defined number of random characters will always be appended to the base62 part. Another example:
+Another option is the minimalRandomKeyLength . If this is set to a value greater than zero the defined number
+of random characters will always be appended to the base62 part. Another example:
 
 * minimalTinyurlKeyLength is 4
 * minimalRandomKeyLength is 3