diff --git a/Documentation/Images/get_link.png b/Documentation/Images/get_link.png new file mode 100644 index 00000000..e91491ab Binary files /dev/null and b/Documentation/Images/get_link.png differ diff --git a/Documentation/Migration/Index.rst b/Documentation/Migration/Index.rst index 3fc22fe5..eecda58b 100644 --- a/Documentation/Migration/Index.rst +++ b/Documentation/Migration/Index.rst @@ -14,11 +14,11 @@ 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: @@ -26,9 +26,9 @@ PHP-based rendering. 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 `__ (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 `. .. _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:`` 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 + + + +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 `. + +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 ` + +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