[TASK] Introduce automatic testing (#349)

* [TASK] Replace .. code-block:: rest with .. code-block:: rst Releases: draft * [TASK] Remove the custom configuration schemes We do not support them anymore in the new rendering Releases: draft * [TASK] Remove outdated information about subtree split This has been outdated since TYPO3 9, the links dont work anymore Release: draft * [TASK] Fix outdated references Release: draft * [TASK] Remove Glossary section We don't support it anymore and it was never really used. Release: draft * [TASK] Introduce automatic testing So that the documentation renders without Release: draft * [TASK] Restore information from migration section That was still linked from these files
TYPO3-Documentation · Jan 14, 2024 · 3d492d9 · 3d492d9
1 parent 951121e
commit 3d492d9
Show file tree

Hide file tree

Showing 35 changed files with 180 additions and 328 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -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
diff --git a/Documentation/BasicPrinciples.rst b/Documentation/BasicPrinciples.rst
@@ -312,13 +312,7 @@ Examples for system extensions are:
 *  `ext:rte_ckeditor <https://docs.typo3.org/typo3cms/extensions/rte_ckeditor/>`__
 
 Note, that if your system has been installed with Composer, not all system extensions may exist
-in the system, if each system extension has been required separately as "subtree splitted packages"
-(not as `typo3/cms`). Since TYPO3 9, installation of "subtree splitted packages" is mandatory.
-
-For more information on subtree split, see
-
-*  `Usetypo3: The TYPO3 Subtree Split and Composer <https://usetypo3.com/typo3-subtree-split-and-composer.html>`__
-*  :ref:`Installation and Upgrade guide: Composer migration <composer-migration-require-subtree-packages>`
+in the system.
 
 
 .. index:: pair: System extensions; Documentation

diff --git a/Documentation/GeneralConventions/CodingGuidelines.rst b/Documentation/GeneralConventions/CodingGuidelines.rst
@@ -48,7 +48,7 @@ Whitespace and indentation
 
 Example:
 
-.. code-block:: rest
+.. code-block:: rst
   :linenos:
 
    .. image:: /Images/a4.jpg
@@ -236,7 +236,7 @@ discouraged either.
 
 The changelog has a title anchor, so you can easily link to it with `:ref:`.
 
-..  code-block:: rest
+..  code-block:: rst
 
     :ref:`ext_core:feature-101544-1691063522`
 
@@ -269,14 +269,14 @@ element or clicked one after the other, use *>* as separator and use
 
 Examples:
 
-.. code-block:: rest
+.. code-block:: rst
 
    Select :guilabel:`File > Open`
 
 How it looks:
    Select :guilabel:`File > Open`
 
-.. code-block:: rest
+.. code-block:: rst
 
    Click on :guilabel:`ADMIN TOOLS > Extensions` in the backend.
 
@@ -296,7 +296,7 @@ When pointing out keyboard shortcuts or keystroke sequences, use
 
 Example:
 
-.. code-block:: rest
+.. code-block:: rst
 
    Press :kbd:`ctrl` + :kbd:`s`
 

diff --git a/Documentation/GeneralConventions/Glossary.rst b/Documentation/GeneralConventions/Glossary.rst
@@ -202,40 +202,3 @@ third party extension
 
 ViewHelper
    Our community agreed on this spelling.
-
-
-
-Glossary
-========
-
-.. https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary
-.. Creating a glossary with terms that you can refer to - obtaining a link.
-
-What terms mean:
-
-.. glossary::
-
-   third party extension
-      Any extension that is not part of the :term:`TYPO3 Core`.
-
-   TYPO3 CMS
-      The TYPO3 content management system.
-
-   TYPO3 Core
-      ...
-
-   TYPO3 Core Team
-      This is the team that drives the development of the :term:`TYPO3 Core`.
-
-
-.. See `Issue on GitHub
-   <https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues/36>`__
-   for discussion about spelling.
-
-.. See open issue about `Clarifying terms
-   <https://github.com/TYPO3-Documentation/T3DocTeam/issues/77>`__
-
-.. Open related issue `Several changes for making TYPO3 concepts easier
-   to understand for new users
-   <https://github.com/TYPO3-Documentation/T3DocTeam/issues/120>`__
-
diff --git a/Documentation/GeneralConventions/GuidelinesForImages.rst b/Documentation/GeneralConventions/GuidelinesForImages.rst
@@ -79,7 +79,7 @@ Here are some :ref:`examples for screenshots <t3contribute:how-to-see-merge-conf
 
 
 
-.. code-block:: rest
+.. code-block:: rst
 
    .. image:: images/github-getting-started-raw.png
       :class: with-shadow

diff --git a/Documentation/GeneralConventions/HowToUpdateDocs.rst b/Documentation/GeneralConventions/HowToUpdateDocs.rst
@@ -84,7 +84,7 @@ Link to changelog
 
 How to link to the changelog is described in :ref:`link-to-changelog`.
 
-..  code-block:: rest
+..  code-block:: rst
 
     :ref:`ext_core:feature-101544-1691063522`
 

diff --git a/Documentation/GeneralConventions/Index.rst b/Documentation/GeneralConventions/Index.rst
@@ -58,7 +58,7 @@ be found in the subchapters.
 
    :ref:`link-to-changelog` describes how to link to the changelog:
 
-   .. code-block:: rest
+   .. code-block:: rst
 
       :ref:`ext_core:feature-101544-1691063522`
 

diff --git a/Documentation/GeneralConventions/ReviewInformation.rst b/Documentation/GeneralConventions/ReviewInformation.rst
@@ -77,7 +77,7 @@ information to the start page:
 :Status:
       Tested and reviewed for TYPO3 9.5.5 on April 11, 2019
 
-.. code-block:: rest
+.. code-block:: rst
 
    :Status:
          Tested and reviewed for TYPO3 9.5.5 on April 11, 2019
@@ -89,7 +89,7 @@ the review information on the start page, for example
 :Status:
       Last tested and reviewed for TYPO3 9.5.5 on April 11, 2019, some pages outdated
 
-.. code-block:: rest
+.. code-block:: rst
 
    :Status:
          Last tested and reviewed for TYPO3 9.5.5 on April 11, 2019, some pages outdated
@@ -119,7 +119,7 @@ cases where updating is not possible immediately.
 
    The information on this page is outdated!
 
-.. code-block:: rest
+.. code-block:: rst
 
    .. warning::
 
@@ -137,7 +137,7 @@ The "todo" directive will not get rendered by default.
 
 Examples of review information with todo:
 
-.. code-block:: rest
+.. code-block:: rst
 
    .. todo:: Needs review: Outdated (2019/5/15 TYPO3 9.5.5)
 

diff --git a/Documentation/WritingDocForExtension/FAQ.rst b/Documentation/WritingDocForExtension/FAQ.rst
@@ -34,11 +34,11 @@ Why Does the Documentation not provide a title?
 .. image:: /Images/missing-title.png
    :class: with-shadow
 
-Refer to :ref:`migrate-necessary-steps` in order to fix this issue.
+Refer to :ref:`migrate` in order to fix this issue.
 
 You must add the project title to your :file:`Settings.cfg`:
 
-.. code-block:: rest
+.. code-block:: rst
 
     [general]
 
@@ -65,7 +65,6 @@ How do I find my new rendered documentation?
 There are several possibilities:
 
 #. Search for the extension on https://docs.typo3.org/Home/Extensions.html.
-#. Or, create URL manually, see :ref:`migrate-url-structure`.
 #. Or, if it was just rerendered, the URL will be referenced from https://intercept.typo3.com/admin/docs/deployments.
    The column **Branch** contains the link.
 

diff --git a/Documentation/WritingDocForExtension/Index.rst b/Documentation/WritingDocForExtension/Index.rst
@@ -109,6 +109,46 @@ Creating extension documentation using the sample manual
    That way others can report issues and assist you by creating change requests to help
    improve both the extensions documentation and the code.
 
+Version numbers
+===============
+
+docs.typo3.org does no longer show three level version numbers in form of ``Major.Minor.Patch``.
+Only the first two levels are shown ``Major.Minor``.
+
+This reduces the amount of documentation while keeping relevant information,
+as patch levels should not introduce breaking changes or new features.
+
+.. index:: Rendering; Branches
+.. _migrate-branches:
+.. _supported-branches:
+
+Supported branches
+==================
+
+The rendering supports two branches within repositories:
+
+``main`` / ``master``
+   Should contain the current development state, used for upcoming release.
+   Every push to these branches triggers a new rendering, available at
+   :samp:`https://docs.typo3.org/p/<vendor>/<package>/main/en-us/`.
+
+   Both branch names are supported, but result in the same URL.
+   Please use ``main``, ``master`` is only supported for backward compatibility.
+
+``documentation-draft``
+   Should contain a draft of the documentation.
+   Every push to this branch triggers a new rendering, available at
+   :samp:`https://docs.typo3.org/p/<vendor>/<package>/draft/en-us/`
+   (same URL as main, except *main* is replaced by *draft*).
+
+
+   This is not indexed by search engines. This branch can be used to test
+   rendering before releasing a new version of an extension.
+
+   In order to test a different rendering, remove the branch, and create it
+   again.
+
+
 .. toctree::
    :maxdepth: 1
    :hidden:

diff --git a/Documentation/WritingDocForExtension/Webhook.rst b/Documentation/WritingDocForExtension/Webhook.rst
@@ -31,7 +31,7 @@ each new extension when requesting rendering for the first time.
 In order to approve an extension, the following things need to apply:
 
 #. The extension needs to be published in TER under the same extension key as
-   claimed by :ref:`t3coreapi:composer.json <composer-json>`.
+   claimed by :ref:`composer.json <t3coreapi:composer-json>`.
 
 #. The Git Repository is referenced from TER detail view page.
 

diff --git a/Documentation/WritingDocsOfficial/GithubMethod.rst b/Documentation/WritingDocsOfficial/GithubMethod.rst
@@ -54,7 +54,7 @@ Workflow #1: "Edit on GitHub"
 
    Every page you edit is written in reST format, when it comes to making minor
    amendments no prior knowledge of editing .rst files is required. However, when you are
-   ready to make more advanced changes, you can :ref:`learn more about working with reST here.<rest-quick-start>`
+   ready to make more advanced changes, you can :ref:`learn more about working with reST here. <rest-quick-start>`
 
 7. Preview your changes:
 

diff --git a/Documentation/WritingReST/BasicRestSyntax.rst b/Documentation/WritingReST/BasicRestSyntax.rst
@@ -57,7 +57,7 @@ The following directive inserts an image in the rendered page. All lines beginni
 two must be indented to the same leve. The convention is to use 4 spaces for one
 level of indentation.
 
-..  code-block:: rest
+..  code-block:: rst
 
     ..  image:: someimage.png
         :class: with-border with-shadow