[TASK] Align with new TYPO3 documentation standards (#503)

alexander-nitsche · web-flow · commit a06bb9ab2a2f · 2022-05-05T00:44:04.000+02:00
diff --git a/.editorconfig b/.editorconfig
@@ -13,7 +13,7 @@ insert_final_newline = true
 trim_trailing_whitespace = true
 
 # ReST-Files
-[*.rst]
+[*.{rst,rst.txt}]
 indent_size = 3
 max_line_length = 80
 
diff --git a/Documentation/Applications/Index.rst b/Documentation/Applications/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 ============
 Applications
@@ -91,7 +90,7 @@ tag
 
    A tag name or tag glob pattern that is understood by `git ls-remote <https://git-scm.com/docs/git-ls-remote.html>`__.
 
-   Surf uses git (:shell:`ls-remote --sort=version`) to sort the results *versiony* and return the highest matching tag.
+   Surf uses git (:bash:`ls-remote --sort=version`) to sort the results *versiony* and return the highest matching tag.
 
    **Example:** ::
 
diff --git a/Documentation/Architecture/Index.rst b/Documentation/Architecture/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 ============
 Architecture
diff --git a/Documentation/CliUsage/Index.rst b/Documentation/CliUsage/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 =========
 CLI Usage
diff --git a/Documentation/DeploymentFlow/Index.rst b/Documentation/DeploymentFlow/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 ===============
 Deployment Flow
diff --git a/Documentation/Examples/Flow/Index.rst b/Documentation/Examples/Flow/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 .. index:: Flow
 
 =======================
diff --git a/Documentation/Examples/Index.rst b/Documentation/Examples/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 ==================
 Deployment Recipes
diff --git a/Documentation/Examples/Laravel/Index.rst b/Documentation/Examples/Laravel/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 .. index:: TYPO3
 
 ==================================
diff --git a/Documentation/Examples/Neos/Index.rst b/Documentation/Examples/Neos/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 .. index:: Neos, Flow
 
 ===========================
diff --git a/Documentation/Examples/Other/Index.rst b/Documentation/Examples/Other/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 
 =====================================
 How to deploy other apps and websites
diff --git a/Documentation/Examples/TYPO3/Index.rst b/Documentation/Examples/TYPO3/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 .. index:: TYPO3
 
 ============================
diff --git a/Documentation/Includes.rst.txt b/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
diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -1,76 +1,70 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: Includes.txt
+.. include:: /Includes.rst.txt
 
-.. _start:
+====
+Surf
+====
 
-TYPO3 Surf |version| documentation
-==================================
+:Package name:
+   typo3/surf
 
-**What is Surf**
+:Version:
+   |release|
 
-Surf package is a complete automated deployment tool.
-It is best used but by far not limited to deploy TYPO3 CMS, Flow and Neos applications.
-It's inspired by some features of Capistrano (thanks) concerning the Git workflow.
+:Language:
+   en
 
-.. only:: html
+:Author:
+   Neos Team & TYPO3 Team & Contributors
 
-   :Classification:
-      deployment
+:License:
+   This document is published under the
+   `Creative Commons BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`__
+   license.
 
-   :Version:
-      |release|
+:Rendered:
+   |today|
 
-   :Language:
-      en
+----
 
-   :Keywords:
-      Surf, Deployment, TYPO3, Flow, Neos
+This package is a powerful and flexible automated deployment tool for PHP
+projects. It is best suited for, but by no means limited to, deploying `TYPO3`_,
+`Flow`_ and `Neos`_ applications. It is inspired by some features of Capistrano
+(thank you) in terms of the Git workflow.
 
-   :Copyright:
-      |copyright|
+.. _TYPO3: https://typo3.org
+.. _Flow: https://flow.neos.io
+.. _Neos: https://www.neos.io
 
-   :Author:
-      The contributors of the TYPO3 Surf project
+----
 
-   :License:
-      The deployment package is licensed under `GNU General Public License <http://www.gnu.org/licenses/gpl.html>`_, version 3 or later.
-      Initial development was sponsored by `networkteam - Flow Framework Agentur <https://networkteam.com/fokus/flow-framework.html>`_.
+**Table of Contents:**
 
-   :Rendered:
-      |today|
-
-**TYPO3**
-
-The content of this document is related to TYPO3 CMS,
-a GNU/GPL CMS/Framework available from `typo3.org <https://typo3.org/>`_ .
-
-**About this manual:**
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   Introduction/Index
+   Installation/Index
+   Usage/Index
+   Architecture/Index
+   DeploymentFlow/Index
+   Applications/Index
+   Nodes/Index
+   Tasks/Index
+   CliUsage/Index
+   SmokeTesting/Index
+   Examples/Index
 
-This is the official documentation to discover the main features and concepts of Surf.
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
 
-If you find an error or something is missing, please:
-`Report a Problem <https://github.com/TYPO3/Surf/issues/new>`__
+   Migration/Index
 
-.. toctree::
-     :hidden:
-     :maxdepth: 2
-     :titlesonly:
-
-     Introduction/Index
-     Installation/Index
-     Usage/Index
-     Architecture/Index
-     DeploymentFlow/Index
-     Applications/Index
-     Nodes/Index
-     Tasks/Index
-     CliUsage/Index
-     SmokeTesting/Index
-     Examples/Index
+.. Meta Menu
 
 .. toctree::
-     :caption: Migration
-     :hidden:
-     :maxdepth: 2
+   :hidden:
 
-     Migration/Index
+   Sitemap
+   genindex
diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 ============
 Installation
diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 ============
 Introduction
diff --git a/Documentation/Migration/Index.rst b/Documentation/Migration/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 ===========================
 Migration from 0.9.x to 2.0
diff --git a/Documentation/Nodes/Index.rst b/Documentation/Nodes/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 =====
 Nodes
diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg
@@ -1,21 +1,29 @@
-[general]
-
-project = Surf
-release = master
-version = 3.3
+# More information about this file:
+# https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#settings-cfg
 
-[notify]
+[general]
 
-about_new_build = no
+project     = Surf
+version     = main
+release     = main
+copyright   = since 2011 by the contributors
 
 [html_theme_options]
 
-github_branch             = master
-github_repository         = TYPO3/Surf
-path_to_documentation_dir = Documentation
+# "Edit on GitHub" button
+github_repository    = TYPO3/Surf
+github_branch        = master
 
-project_home       = https://github.com/TYPO3/Surf
-project_issues     = https://github.com/TYPO3/Surf/issues
-project_repository = https://github.com/TYPO3/Surf
+# Footer links
+project_home         = https://packagist.org/packages/TYPO3/Surf
+project_contact      = https://typo3.slack.com/archives/C02EG058U
+project_repository   = https://github.com/TYPO3/Surf
+project_issues       = https://github.com/TYPO3/Surf/issues
+project_discussions  =
+
+use_opensearch       =
 
 [intersphinx_mapping]
+
+# Official TYPO3 manuals
+# t3home         = https://docs.typo3.org/
diff --git a/Documentation/Sitemap.rst b/Documentation/Sitemap.rst
@@ -0,0 +1,9 @@
+:template: sitemap.html
+
+.. include:: /Includes.rst.txt
+
+=======
+Sitemap
+=======
+
+.. The sitemap.html template will insert here the page tree automatically.
diff --git a/Documentation/SmokeTesting/Index.rst b/Documentation/SmokeTesting/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 =============
 Smoke Testing
diff --git a/Documentation/Tasks/Index.rst b/Documentation/Tasks/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 =====
 Tasks
diff --git a/Documentation/Usage/Index.rst b/Documentation/Usage/Index.rst
@@ -1,5 +1,4 @@
-.. -*- coding: utf-8 -*- with BOM.
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 =====
 Usage
diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst
@@ -0,0 +1,7 @@
+.. include:: /Includes.rst.txt
+
+=====
+Index
+=====
+
+.. Sphinx will insert here the general index automatically.
diff --git a/README.md b/README.md
diff --git a/composer.json b/composer.json
