DOC: added more documentation and examples for crawler macros

src/doc/macros.rst

@@ -37,7 +37,7 @@ The same version using cfood macros could be defined as follows:
         name: null
         filename: null
       definition:
-        ${name}_filename
+        ${name}_filename:
           type: SimpleFile
           match: $filename
           records:
@@ -56,13 +56,40 @@ The same version using cfood macros could be defined as follows:
       - name: README
         filename: ^README.md$
 
+The expanded version of `ExperimentalData` will look like:
 
+.. _example_files_2_expanded:
+.. code-block:: yaml
 
+  ExperimentalData:
+    match: ExperimentalData
+    subtree:
+      README_filename:
+        match: ^README.md$
+        records:
+          README:
+            file: README_filename
+            parents:
+            - MarkdownFile
+            path: README_filename
+            role: File
+        type: SimpleFile
+    type: Directory
+
+This :ref:`example<_example_files_2>` can also be found in the macro unit tests (see :func:`unittests.test_macros.test_documentation_example_2`).
 
 
 Complex Example
 ===============
 
+The following, more complex example, demonstrates the use
+of macro variable substitutions that generate crawler variable substitutions:
+
+- `$$$nodename` will lead to a macro variable substitution of variable `$nodename` during macro expansion.
+- `$$` will be turned into `$`
+- So in the crawler cfood, the string will appear as `$value` if variable `nodename` would be set to `value` when using the macro.
+
+
 .. _example_1:
 .. code-block:: yaml
    
@@ -86,3 +113,118 @@ Complex Example
                file: $$$nodename
              Simulation:
                $recordtype: +$File
+
+The expanded version of :ref:`example<_example_1>` can be seen in :ref:`example<_example_1_expanded>`.
+
+
+.. _example_1_expanded:
+.. code-block:: yaml
+                
+  SimulationData:
+    match: SimulationData
+    subtree:
+      Dataset:
+        match: .*
+        records:
+          File:
+            file: $Dataset
+            parents:
+            - DatasetFile
+            path: $Dataset
+            role: File
+          Simulation:
+            DatasetFile: +$File
+        type: SimpleFile
+    type: Directory
+
+This :ref:`example<_example_1>` can also be found in the macro unit tests (see :func:`unittests.test_macros.test_documentation_example_1`).
+
+
+
+Using Macros Multiple Times
+===========================
+
+To use the same macro multiple times in the same yaml node, lists can be used:
+
+.. _example_multiple:
+.. code-block:: yaml
+
+    ---
+    metadata:
+      macros:
+        - !defmacro
+          name: test_twice
+          params:
+            macro_name: default_name
+            a: 4
+          definition:
+            $macro_name:
+              something:
+                a: $a
+    ---
+    extroot: !macro
+      test_twice:
+      - macro_name: once  # <- This is the first replacement of the macro
+      - macro_name: twice # <- This is the second one, with different arguments
+        a: 5
+      - {}                # <- This is the third one, just using default arguments
+
+        
+This :ref:`example<_example_multiple>` is taken from the macro unit tests (see :func:`unittests.test_macros.test_use_macro_twice`).
+
+The example will be expanded to:
+
+.. _example_multiple_expanded:
+.. code-block:: yaml
+
+    extroot:
+      default_name:
+        something:
+          a: '4'
+      once:
+        something:
+          a: '4'
+      twice:
+        something:
+          a: '5'
+
+
+
+
+Limitation
+----------
+
+Currently it is not possible to use the same macro twice in the same yaml node, but in different
+positions. Consider:
+
+.. _example_multiple_limitation:
+.. code-block:: yaml
+
+    ---
+    metadata:
+      macros:
+        - !defmacro
+          name: test_twice
+          params:
+            macro_name: default_name
+            a: 4
+          definition:
+            $macro_name:
+              something:
+                a: $a
+    ---
+    extroot: !macro
+      test_twice:
+      - macro_name: once  # <- This is the first replacement of the macro
+        
+      Other_node:
+        type: test
+        
+      test_twice:  # This is NOT possible as each
+                   #  dictionary element can only appear once in a yaml node.
+      - macro_name: twice # <- This is the second one, with different arguments
+        a: 5
+      - {}                # <- This is the third one, just using default arguments
+
+However, this should not be a real limitation, as the crawler is designed in a way,
+that the order of the nodes in the same level should not matter.