docs: add explaination about includes

doc-migration/README.md

@@ -69,6 +69,42 @@ We use the following Sphinx extensions to achieve parity with the old docs:
 
 Allows referencing variables in the `global_substitutions` object in `/doc-migrations/source/conf.py` (the Sphinx config file).
 
+## The `rst` file
+
+### Includes
+
+1. Versions
+   In the Docbook files you may find lines like these: `<xi:include href="version-info.xml" xpointer="v205"/>` which would render into `Added in version 205` in the docs. This is now archived with the existing [sphinx directive ".. versionadded::"](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded) and represented as `.. versionadded:: 205` in the rst file
+
+2. Code Snippets
+These can be included with the [literalinclude directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude) when living in their own file.
+Example:
+```
+.. literalinclude:: ./check-os-release-simple.py
+:language: python
+
+```
+
+There is also the option to include a [code block](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) directly in the rst file.
+Example:
+```
+.. code-block:: sh
+
+a{sv} 3 One s Eins Two u 2 Yes b true
+
+```
+3. Text Snippets
+
+There are a few xml files were sections of these files are reused in multiple other files. While it is no problem to include a whole other rst file the concept of only including a part of that file is a bit more tricky. You can choose to include text partial that starts after a specific text and also to stop before reaching another text. So we decided it would be best to add start and stop markers to define the section in these source files. These markers are: `.. inclusion-marker-do-not-remove` / ``
+So that a `<xi:include href="standard-options.xml" xpointer="no-pager" />` turns into:
+```
+.. include:: ./standard-options.rst
+  :start-after: .. inclusion-marker-do-not-remove no-pager
+  :end-before: .. inclusion-end-marker-do-not-remove no-pager
+```
+
+Files that only have content that will be included in other files and therefore should not be part of the index have the `:orphan:` tag. This will suppress warnings about this file not being in the toctree.
+
 ## Todo:
 
 An incomplete list.