[TASK] Improve wording and add some additions to migration (#407)

* [TASK] Improve wording and add some additions to migration * Update Documentation/Migration/Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Documentation/Migration/Index.rst Correct wording Co-authored-by: Lina Wolf <[email protected]> * Update Documentation/Migration/Index.rst Co-authored-by: Lina Wolf <[email protected]> * Update Documentation/Migration/Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Documentation/Migration/Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Documentation/Migration/Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Documentation/Migration/Index.rst Co-authored-by: Chris Müller <[email protected]> * [FIX] Fix indentation * Correct wording * Fixing some pieces * Fix problems from comments --------- Co-authored-by: Chris Müller <[email protected]> Co-authored-by: Lina Wolf <[email protected]>
TYPO3-Documentation · Apr 17, 2024 · 176d065 · 176d065
1 parent 4348b29
commit 176d065
Show file tree

Hide file tree

Showing 2 changed files with 170 additions and 12 deletions.
diff --git a/Documentation/Images/get_link.png b/Documentation/Images/get_link.png
diff --git a/Documentation/Migration/Index.rst b/Documentation/Migration/Index.rst
@@ -14,21 +14,21 @@ Migration: From Sphinx to PHP-based rendering
     Text rendering to try it out. The new rendering will become mandatory in
     August 2024.
 
-The main difference that concerns you is that the PHP-based rendering
-requires a file called :file:`Documentation/guides.xml` for configuration
-while in Sphinx rendering a file called :file:`Documentation/Settings.cfg` was
-used. In the transition period we detect if a file called
-:file:`Documentation/guides.xml` is present and then switch to the
+The main difference compared to the Sphinx rendering is that the PHP-based rendering
+requires a file called :file:`Documentation/guides.xml` for configuration.
+The Sphinx rendering required a file called :file:`Documentation/Settings.cfg`.
+In the transition period the GitHub action of the official rendering process detects if a file called
+:file:`Documentation/guides.xml` is present and then automatically switches to the
 PHP-based rendering.
 
 ..  _migrate_guides_xml:
 
 Create the settings file :file:`Documentation/guides.xml`
 =========================================================
 
-The Docker container for the PHP-based rendering additionally contains
+The Docker container for the PHP-based rendering additionally consists out of
 a migration tool. This tool can be used to automatically create a
-:file:`Documentation/guides.xml` from the information contained in your
+:file:`Documentation/guides.xml` based on the information contained in your
 :file:`Documentation/Settings.cfg`.
 
 `Docker <https://docs.docker.com/install/>`__ (or a drop-in replacement like
@@ -59,13 +59,25 @@ operating system for the tool to work:
 The last parameter (:bash:`Documentation`) is the name of the directory, where your
 :file:`Settings.cfg` is currently placed in.
 
-After the migration is performed, you will see output about which settings were
-converted, if some old settings were discarded, or errors occurred.
+After the migration is performed, you will see some output in the terminal about which settings were
+converted, if some old settings were discarded, or errors occurred. When you see this:
+
+..  code-block:: text
+    :caption: Output of the command
+
+    Note: Some of your settings could not be converted:
+        * html_theme_options
+        * project_discussions
+        * use_opensearch
+
+everything went well. They can be ignored since these files are usually files that
+not need to be converted. You can now delete :file:`Settings.cfg`. If you ever should need it again it is still in the Git history. Also delete
+file :file:`genindex.rst` in your Documentation directory (if available).
 
 Try out the rendering locally
 =============================
 
-Use our Docker container to render your documentation locally. Read more about
+Use our Docker container to render your documentation locally. Read more about it in
 :ref:`local rendering <rendering-docs>`.
 
 ..  _migrate-detailed-steps:
@@ -78,6 +90,22 @@ PHP-based rendering tool:
 
 ..  rst-class:: bignums
 
+#.  Manual modifications of the :file:`guides.yml`
+
+    You have to manually change the following: in the :xml:`<extension>` tag add the attribute
+
+        ..  code-block:: text
+            :caption: Changes in your :file:`guides.yml`
+
+            interlink-shortcode="my-vendor/my-extension"
+
+    You can find the package name in your :file:`composer.json` file under "name".
+    For example, :json:`my-vendor/my-extension`.
+    We recommend to reformat the code, for example in PhpStorm, using the Mac shortcut
+    :kbd:`cmd (⌘)` + :kbd:`option/alt (⌥)` + :kbd:`L`, or :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`L`
+    on Windows/Linux and to use for every attribute one line.
+
+
 #.  Improve your documentation to render without warning
 
     Rendering your documentation should not yield any warnings or errors.
@@ -174,6 +202,136 @@ of typing a long :bash:`docker run...` or :bash:`podman run...` command:
 
     make docs
 
+You should see something like this
+
+.. code-block:: text
+
+    Successfully placed 7 rendered HTML, SINGLEPAGE, and INTERLINK files into /project/Documentation-GENERATED-temp
+
+..  _migrate-possible-errors:
+
+Possible errors using `make docs`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We provide four example errors to guide you through the fixes.
+
+..  _migrate-interlink-inventory-not-found:
+
+Interlink inventory not found: HTTP/2 404
+"""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: text
+
+    [2024-03-13T12:22:50.661532+00:00] app.WARNING: Interlink inventory not found: HTTP/2 404
+    returned for "https://docs.typo3.org/m/typo3/book-extbasefluid/11.5/en-us/objects.inv.json". [] []
+
+Here you see that the link `https://docs.typo3.org/m/typo3/book-extbasefluid/11.5/en-us` is not found (404 page).
+We can now check via Google if there is another link to book Extbasefluid. We found this site `https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/`
+We can find the hint: `This manual is no longer being maintained for TYPO3 versions 11.5 and above.`. This tells us that the Documentation Team abandoned this
+manual. We can, for example, link to the last existing version. Which is 10.4. To do this we have to change the :file:`guides.xml`. Search for the
+
+.. code-block:: xml
+
+    <inventory id="t3extbasebook"
+           url="https://docs.typo3.org/m/typo3/book-extbasefluid/11.5/en-us/"
+    />
+
+and change `11.5` to `10.4`. Generate files again. Keep in mind, that this is a
+workaround to avoid warnings temporarily. References to outdated manuals should be adjusted
+as soon as possible.
+
+
+..  _migrate-inventory-link-with-key-not-found:
+
+Inventory link with key ... not found
+"""""""""""""""""""""""""""""""""""""
+
+.. code-block:: text
+
+    [2024-03-13T12:26:40.940930+00:00] app.WARNING: Inventory link with key "h2document:rest-common-pitfalls"
+    (rest-common-pitfalls) not found.  {"rst-file":"GeneratedExtension/Index","type":"ref","targetRef
+
+We see already that we have to go to file :file:`GeneratedExtension/Index` in the directory "Documentation".
+In there we have to delete the line which contains
+
+.. code-block:: text
+
+    * :ref:`h2document:rest-common-pitfalls`
+
+But whether we should delete the reference or not depends on the special case. In this case the whole section was removed.
+So here it is useful to delete the reference.
+We conclude: In general it depends on the case itself what the best solution is.
+
+..  _migrate-nested-php-domain-components-not-supported:
+
+Nested PHP domain components (php:class, php:interface, php:enum etc) are not supported
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: text
+
+    [2024-03-25T13:26:11.600367+00:00] app.WARNING: Nested PHP domain components
+    (php:class, php:interface, php:enum etc) are not supported.
+    Found php:\Vendor\MyExtension\Interfaces\RequireJsModuleInterface inside
+    \Vendor\MyExtension\Interfaces\AnotherImportantInterface {"rst-file":"Developer/Index.rst"} []
+
+The file :file:`Index.rst` in :file:`Documentation/Developer/` has a wrong indentation. A class must not belong to another class.
+Here is the wrong rst code.
+
+.. code-block:: rst
+
+    ..  php:class:: AnotherImportantInterface
+
+        Used for ...
+
+        ..  php:class:: RequireJsModuleInterface
+
+        Widgets implementing this interface will add the provided RequireJS modules.
+        Those modules will be loaded in dashboard view if the widget is added at least once.
+
+Additionally regarding the name it has to be interfaces and not classes.
+:rst:`..  php:class:: ExampleInterface` has to be changed to :rst:`..  php:interface:: ExampleInterface`.
+
+
+..  _migrate-reference-could-not-be-resolved:
+
+Reference sitehandling-addinglanguages could not be resolved in LocalizedContent/Index {"rst-file":"LocalizedContent/Index"} []
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The next step is to visit the site which was rendered with the Sphinx rendering, in our example
+`https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/LocalizedContent/Index.html`.
+There we can search for `sitehandling-addinglanguages` in the restructured text code by clicking the button "`</> View Source`".
+We have found this:
+
+.. code-block:: rst
+
+    ..  tip::
+        For more information on how to add languages and configure their
+        behaviour in the site configuration, see
+        :ref:`Adding Languages <sitehandling-addinglanguages>`.
+
+The link is leading to
+`https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/AddLanguages.html#sitehandling-addinglanguages`.
+We have to click the symbol next to the heading and copy the correct link
+which is the one for restructured text
+
+.. image:: /Images/get_link.png
+    :class: with-shadow
+    :width: 600px
+
+.. code-block:: rst
+
+    :ref:`Adding Languages <t3coreapi:sitehandling-addingLanguages>`
+
+You have to replace the correct link in, for example, :file:`Documentation/LocalizedContent/Index.rst` to
+fix the error. Note: Since we already migrated the Frontend Localization Guide
+(`https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/LocalizedContent/Index.html`)
+to use the PHP-based rendering you cannot find the state that we have shown above anymore.
+
+..  _migrate-makefile-example-code:
+
+Makefile example
+~~~~~~~~~~~~~~~~
+
 For inspiration, check out the :file:`Makefile` of the main PHP-based rendering
 repository:
 
@@ -206,10 +364,10 @@ It is recommended to use an automatic workflow on GitHub Or GitLab to
 ensure the extension's documentation renders without warnings.
 
 An example workflow on GitHub would be established via this file in
-:file:`.github/actions/documentation.yml`:
+:file:`.github/workflows/documentation.yml`:
 
 ..  literalinclude:: /CodeSnippets/_documentation.yml
-    :caption: .github/actions/documentation.yml
+    :caption: .github/workflows/documentation.yml
 
 
 This creates a workflow entry `Test documentation`, so that on every push to your