[TASK] Add in-depth notes for migration (#403)

* [TASK] Add in-depth notes for migration

* Apply suggestions from code review

Co-authored-by: Chris Müller <[email protected]>

* [TASK] Implement changes from code review

* [TASK] Use bignum formatting

* [TASK] Enhances Makefile with a "test-docs" command

* [TASK] Tell about Makefile tab indentation oddities

* [TASK] Remove "screenshots.json" reference

* Update Documentation/WritingDocForExtension/Migrate.rst

Co-authored-by: Chris Müller <[email protected]>

* Apply suggestions from code review

Co-authored-by: Chris Müller <[email protected]>

* [TASK] Implement review feedback

* [TASK] Use diff syntax instead emphasize-lines

* Small adjustments

---------

Co-authored-by: Chris Müller <[email protected]>

.editorconfig

@@ -21,3 +21,7 @@ trim_trailing_whitespace = true
 indent_style = space
 indent_size = 4
 max_line_length = 80
+
+[{Makefile,_Makefile}]
+# Use tabs for indentation (Makefiles require tabs)
+indent_style = tab

Documentation/WritingDocForExtension/Migrate.rst

@@ -1,9 +1,9 @@
-.. include:: /Includes.rst.txt
-.. index::
-   Documentation; Migration
-   docs.typo3.org
-.. _migrate:
-.. _register-for-rendering:
+..  include:: /Includes.rst.txt
+..  index::
+    Documentation; Migration
+    docs.typo3.org
+..  _migrate:
+..  _register-for-rendering:
 
 =============================================
 Migration: From Sphinx to PHP-based rendering
@@ -15,49 +15,230 @@ 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 new PHP-base rendering
+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:`Docuemtation/Settings.cfg` was
+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 new
+:file:`Documentation/guides.xml` is present and then switch to the
 PHP-based rendering.
 
 ..  _migrate_guides_xml:
 
 Create the settings file :file:`Documentation/guides.xml`
 =========================================================
 
-The Docker container for the new PHP-based rendering additionally contains
+The Docker container for the PHP-based rendering additionally contains
 a migration tool. This tool can be used to automatically create a
 :file:`Documentation/guides.xml` from the information contained in your
 :file:`Documentation/Settings.cfg`.
 
-`Docker <https://docs.docker.com/install/>`__ needs to be installed on your
+`Docker <https://docs.docker.com/install/>`__ (or a drop-in replacement like
+`Podman <https://podman.io>`__) needs to be installed on your
 operating system for the tool to work:
 
-..  code-block:: shell
+..  tabs::
+
+    ..  group-tab:: Docker
+
+        ..  code-block:: bash
+
+            docker run --rm --pull always \
+              -v $(pwd):/project \
+              -it ghcr.io/typo3-documentation/render-guides:latest \
+              migrate Documentation
+
+    .. group-tab:: Podman
+
+        ..  code-block:: bash
+
+            podman run --rm --pull always \
+              -v $(pwd):/project \
+              -it ghcr.io/typo3-documentation/render-guides:latest \
+              migrate Documentation
+
+
+The last parameter (:bash:`Documentation`) is the name of the directory, where your
+:file:`Settings.cfg` is currently placed in.
 
-    docker run --rm --pull always \
-        -v $(pwd):/project \
-        -it ghcr.io/typo3-documentation/render-guides:latest \
-        migrate Documentation
+After the migration is performed, you will see output about which settings were
+converted, if some old settings were discarded, or errors occurred.
 
 Try out the rendering locally
 =============================
 
 Use our Docker container to render your documentation locally. Read more about
 :ref:`local rendering <rendering-docs>`.
 
-Improve your documentation to render without warning
-====================================================
+..  _migrate-detailed-steps:
+
+Further steps to adapt to the PHP-based rendering
+=================================================
+
+You should perform the following tasks to conclude the migration to the
+PHP-based rendering tool:
+
+..  rst-class:: bignums
+
+#.  Improve your documentation to render without warning
+
+    Rendering your documentation should not yield any warnings or errors.
+
+    If you get error messages, often they refer to wrong indentation, missing
+    :ref:`interlinks <settings-guides-interlink-mapping>`, orphaned files or
+    outdated ReST identifiers.
+
+    If you are unable to address a warning/error with changes in your documentation
+    feel free to ask in Slack channel #typo3-documentation (see :ref:`how-to-get-help`).
+
+    If you believe you found a specific bug in the PHP-based rendering, please open
+    an `issue on GitHub <https://github.com/TYPO3-Documentation/render-guides/issues>`__.
+
+#.  Remove outdated files
+
+    After the :file:`guides.xml` file has been created, you can remove the old
+    :file:`Settings.cfg` file.
+
+    You can also delete the :file:`genindex.rst` file which was previously used
+    to generate an index.
+
+#.  Adapt :file:`Includes.rst.txt`
+
+    The main documentation directory can contain a file :file:`Includes.rst.txt`
+    to include any fixed text, which will be placed on every page of your rendered
+    documentation.
+
+    Previously, it was also used to define a list of utilized directives/roles.
+
+    You can either remove that file, or add your fixed text to it. If you remove
+    the file, remember to also remove all references pointing to that file, like:
+
+    ..  code-block:: text
+        :caption: Documentation/Index.rst
+
+        ..  include:: /Includes.rst.txt
+
+    Most official documentation uses this as the stub of the file:
+
+    ..  code-block:: text
+        :caption: Documentation/Includes.rst.txt
+
+        ..  You can put central messages to display on all pages here
+
+#.  Remove the entry `genindex` from :file:`Index.rst` (Index/Glossary)
+
+    If you previously had a :file:`genindex.rst` file, this optional index
+    (or glossary) was rendered as a page through an entry in the file :file:`Index.rst`
+    like this:
+
+    ..  code-block:: diff
+        :caption: Documentation/Index.rst
+
+         .. toctree::
+            :hidden:
+
+            Sitemap
+        -   genindex
 
-If you believe you found a bug in the new PHP-based rendering, please open
-an `Issue on GitHub <https://github.com/TYPO3-Documentation/render-guides/issues>`__.
+    Remove the entry `genindex` from the list.
 
-Recommended: Activate automatic testing
-=======================================
+    ..  hint::
 
-It is recommended to use an automatic workflow on GitHub Or Gitlab to
+        See :ref:`migrate-glossary` for details about the future of the
+        index (glossary) generation.
+
+#.  Avoid code snippets with :file:`.rst` extension
+
+    All files with the extension :file:`.rst` will be interpreted by the PHP-based
+    rendering, and every file that is just a code snippet placed in an external file
+    should be renamed to use a :file:`.rst.txt` extension instead.
+
+Recommendations
+===============
+
+The following list is not a requirement to utilize the PHP-based rendering, but
+follows "best practice" to make the most of your documentation project.
+
+..  _migrate-to-makefile:
+
+Add a :file:`Makefile` to your project
+--------------------------------------
+
+A :file:`Makefile` is a simple command line runner configuration file, which requires
+the utility `GNU make <https://www.gnu.org/software/make/manual/make.html>`_
+to be available on your Unix-based operating system (Linux, macOS, WSL on Windows,
+for example).
+
+This allows you to perform shortcuts to render your documentation instead
+of typing a long :bash:`docker run...` or :bash:`podman run...` command:
+
+..  code-block:: shell
+
+    make docs
+
+For inspiration, check out the :file:`Makefile` of the main PHP-based rendering
+repository:
+
+https://github.com/TYPO3-Documentation/render-guides/blob/main/Makefile
+
+A small example :file:`Makefile`:
+
+..  literalinclude:: _Makefile
+    :caption: Makefile
+
+..  hint::
+
+    Makefile blocks need to be indented with a TAB character, not spaces.
+    If your project comes with an :ref:`editorconfig` definition for
+    code formatting, you should add the following:
+
+    ..  code-block:: text
+
+        [Makefile]
+        # Use tabs for indentation (Makefiles require tabs)
+        indent_style = tab
+
+
+..  _migrate-to-testing-workflow:
+
+Activate automatic testing in your project
+------------------------------------------
+
+It is recommended to use an automatic workflow on GitHub Or GitLab to
 ensure the extension's documentation renders without warnings.
 
-..  todo: Add a link to the according chapter
+An example workflow on GitHub would be established via this file in
+:file:`.github/actions/documentation.yml`:
+
+..  literalinclude:: _documentation.yml
+    :caption: .github/actions/documentation.yml
+
+
+This creates a workflow entry `Test documentation`, so that on every push to your
+repository, and every pull request, the rendering is executed. A commit will then
+not be possible, if the rendering fails. The workflow run will be marked with an error,
+and shown on pull requests.
+
+..  _migrate-glossary:
+
+To be discussed: Index generation (glossary)
+============================================
+
+The Sphinx rendering allowed to utilize a syntax like the following to
+add indexes to your documentation:
+
+..  code-block::
+    :caption: Documentation/Index.rst
+
+    ..  index::
+        XLIFF; Files
+        File; XLIFF
+
+The automatically generated file :file:`genindex.html` would show a
+two-column layout of all indexes, with the pages that they were used on.
+
+The PHP-based rendering does not (yet) support this indexing.
+
+The current recommendation is to only remove the :file:`genindex.rst` file
+from your documentation directory, but keep all the placed `..  index`
+directives. If at some point the automatic index generation is re-introduced,
+your old indexes will be able to show up again.

Documentation/WritingDocForExtension/_Makefile

@@ -0,0 +1,16 @@
+.PHONY: help
+help: ## Displays this list of targets with descriptions
+	@echo "The following commands are available:\n"
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
+
+
+.PHONY: docs
+docs: ## Generate projects docs (from "Documentation" directory)
+	mkdir -p Documentation-GENERATED-temp
+	docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
+
+
+.PHONY: test-docs
+test-docs: ## Test the documentation rendering
+	mkdir -p Documentation-GENERATED-temp
+	docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log

Documentation/WritingDocForExtension/_documentation.yml

@@ -0,0 +1,17 @@
+name: Test documentation
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    name: Render 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

Makefile

@@ -7,5 +7,10 @@ help: ## Displays this list of targets with descriptions
 .PHONY: docs
 docs: ## Generate projects docs (from "Documentation" directory)
 	mkdir -p Documentation-GENERATED-temp
-
 	docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
+
+
+.PHONY: test-docs
+test-docs: ## Test the documentation rendering
+	mkdir -p Documentation-GENERATED-temp
+	docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log