[TASK] Adjust rendering page (#347)

* [TASK] Adjust rendering page Releases: draft * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <[email protected]> * [TASK] Apply suggestions from code review * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <[email protected]> * [TASK] Apply suggestions from code review --------- Co-authored-by: Chris Müller <[email protected]>
TYPO3-Documentation · Jan 13, 2024 · 951121e · 951121e
1 parent bc30031
commit 951121e
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 247 deletions.
diff --git a/Documentation/RenderingDocs/Index.rst b/Documentation/RenderingDocs/Index.rst
@@ -10,97 +10,116 @@
 .. _render-documenation-with-docker:
 .. _render-documentation-with-docker:
 
+=========================================
+Render documentation with the TYPO3 theme
+=========================================
 
-===========================
-How to render documentation
-===========================
+..  contents::
 
-This page explains how to render a manual locally on your machine
-with Docker in order to test the rendering.
+Rendering the :file:`Documentation` folder locally with Docker
+==============================================================
 
-Run these commands in a terminal in the parent directory of the directory
-:file:`Documentation`. You should use a bash compatible shell, if possible.
+You can render the documentation of an official TYPO3 manual or a third-party
+manual with the following steps:
 
-If you run into a problem while rendering, check :ref:`rendering-docs-troubleshooting`,
-`report an issue <https://github.com/t3docs/docker-render-documentation/issues/new>`__
-or :ref:`ask for help <get-help-on-writing-docs>`.
+#.  Clone the repository containing the documentation.
 
+#.  Navigate to the extension's root folder, the directory which contains the
+    :file:`composer.json`.
 
-.. rst-class:: bignums-xxl
+#.  Check if there is documentation to be rendered:
 
-    #.  Install Docker: https://docs.docker.com/install/
+    A folder called :file:`Documentation` containing at least the files
+    :file:`Index.rst` and :file:`guides.xml`.
 
-    #.  Preparations
+#.  Choose your prefered method of rendering (See below):
 
-        The docker image is not listed on Docker Hub (hub.docker.com) anymore, therefore some preparations
-        need to be done once:
+Make sure that `Docker <https://www.docker.com/>`__ is installed on your system.
 
-        ..  code-block:: bash
+.. tabs::
 
-            # pull 'latest' version from GitHub container repository
-            docker pull ghcr.io/t3docs/render-documentation
+    ..  group-tab:: Linux
 
-            # The "real" tag is independent of the container repository,
-            # so let's just create that extra "real" and "generic" tag
-            docker tag ghcr.io/t3docs/render-documentation t3docs/render-documentation
+        ..  code-block:: bash
 
-            # verify it worked
-            docker run --rm t3docs/render-documentation --version
+            mkdir -p Documentation-GENERATED-temp
+            docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
+            xdg-open "Documentation-GENERATED-temp/Index.html"
 
-    #.  Make 'dockrun_t3rd' available in current terminal
+    .. group-tab:: MacOS
 
-        .. code-block:: bash
+        ..  code-block:: bash
 
-            eval "$(docker run --rm t3docs/render-documentation show-shell-commands)"
+            mkdir -p Documentation-GENERATED-temp
+            docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
+            open "Documentation-GENERATED-temp/Index.html"
 
-        This will run the Docker container and print out shell code. Once "eval-uated" 
-        the code defines a helper function named `dockrun_t3rd`. This function relieves 
-        you of the work of setting the volumes and rights correctly when running the 
-        container and ensures a folder for the rendering results is provided. Executing 
-        the code with `eval` defines the function for your current terminal. Don't forget
-        the quotes around everything that goes into eval. Either define the function each
-        time you open a new terminal window or add the line to the startup file of your
-        shell like `~/.bashrc` or `.zshrc`.
+    ..  group-tab:: Windows
 
-    #.  Run dockrun_t3rd
+        ..  code-block:: powershell
 
-        .. code-block:: bash
+            New-Item -ItemType Directory -Force -Path ".\Documentation-GENERATED-temp"
+            docker run --rm --pull always -v ${PWD}:/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
+            start "Documentation-GENERATED-temp/Index.html"
 
-            dockrun_t3rd makehtml
+Publishing extension documentation to docs.typo3.org
+====================================================
 
-        This will automatically find the documentation in the
-        :file:`Documentation` subfolder. It will create a directory
-        :file:`Documentation-GENERATED-temp` and write the results there.
+For your documentation to be published to https://docs.typo3.org, your
+TYPO3 extension has to have a valid :file:`composer.json` and either a folder
+called :file:`Documentation` with a :file:`Documentation/Index.rst` and
+a :file:`Documentation/guides.xml` or a :file:`README.rst` / :file:`README.md`
+in the extensions root directory.
 
-    #.  Open generated documentation
+The extension has to be publicly available on GitHub or GitLab. You have to
+establish a :ref:`Webhook <webhook>` and the Documentation Team has to
+:ref:`approve <approval-intercept>` your first rendering.
 
-        Look at the output of the previous command to see where the
-        generated documentation is located or use one of these commands
-        to directly open the start page in a browser:
+Introduce automatic testing for extension documentation
+=======================================================
 
-        .. tabs::
+It is recommended to make sure your documentation always renders without
+warning. On GitHub or GitLab you can introduce actions that test your
+documentation automatically:
 
-          .. group-tab:: Linux
+.. tabs::
 
-             .. code-block:: bash
+    ..  group-tab:: GitHub
 
-                xdg-open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
+        ..  code-block:: yaml
+            :caption: .github/workflows/documentation.yml
 
-          .. group-tab:: MacOS
+            name: test documentation
 
-             .. code-block:: bash
+            on: [ push, pull_request ]
 
-                open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
+            jobs:
+              tests:
+                name: documentation
+                runs-on: ubuntu-latest
+                steps:
+                  - name: Checkout
+                    uses: actions/checkout@v4
 
-          .. group-tab:: Windows
+                  - 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
 
-             .. code-block:: powershell
+    .. group-tab:: GitLab
 
-                start "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
+        ..  code-block:: bash
+            :caption: .gitlab-ci.yml
 
+            stages:
+              - test
 
-.. toctree::
-   :hidden:
-   :glob:
+            test_documentation:
+              stage: test
+              script:
+                - 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
+              tags:
+                - docker
 
-   Troubleshooting
diff --git a/Documentation/RenderingDocs/Troubleshooting.rst b/Documentation/RenderingDocs/Troubleshooting.rst