docs: yaml loading complete setup

docs/docs/core-components/output/drawio/yaml3.drawio

@@ -0,0 +1,57 @@
+<mxfile host="multicloud-diagrams" agent="PIP package multicloud-diagrams. Generate resources in draw.io compatible format for Cloud infrastructure. Copyrights @ Roman Tsypuk 2023. MIT license." type="MultiCloud">
+	<diagram id="diagram_1" name="AWS components">
+		<mxGraphModel dx="1015" dy="661" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="1">
+			<root>
+				<mxCell id="0" />
+				<mxCell id="1" parent="0" />
+				<mxCell id="vertex:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name" value="&lt;b&gt;Name&lt;/b&gt;: prod-lambda-name&lt;BR&gt;&lt;b&gt;ARN&lt;/b&gt;: arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name" style="verticalLabelPosition=bottom;verticalAlign=top;aspect=fixed;align=left;pointerEvents=1;shape=mxgraph.aws3.lambda_function;prIcon=server;fillColor=#F58534;gradientColor=none;html=1;" parent="1" vertex="1">
+					<mxGeometry width="69" height="72" as="geometry" x="100" y="-230" />
+				</mxCell>
+				<mxCell id="vertex:dynamo:arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table" value="&lt;b&gt;Name&lt;/b&gt;: prod-dynamo-table&lt;BR&gt;&lt;b&gt;ARN&lt;/b&gt;: arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table" style="outlineConnect=0;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=left;html=1;shape=mxgraph.aws3.dynamo_db;fillColor=#2E73B8;gradientColor=none;" parent="1" vertex="1">
+					<mxGeometry width="72" height="81" as="geometry" x="100" y="-70" />
+				</mxCell>
+				<mxCell id="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:dynamo:arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table" style="endFill=0;endArrow=none;endArrow=none;" parent="1" source="vertex:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name" target="vertex:dynamo:arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table" edge="2">
+					<mxGeometry as="geometry" />
+				</mxCell>
+				<mxCell id="label:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:dynamo:arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table" value="GET permissions" style="edgeLabel;html=1;align=left;verticalAlign=middle;resizable=0;points=[];labelBackgroundColor=none;" parent="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:dynamo:arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table" vertex="1" connectable="0">
+					<mxGeometry relative="1" as="geometry">
+						<mxPoint as="offset" />
+					</mxGeometry>
+				</mxCell>
+				<mxCell id="vertex:mq_broker:host.broker.com" value="&lt;b&gt;Name&lt;/b&gt;: event-broker&lt;BR&gt;&lt;b&gt;ID&lt;/b&gt;: host.broker.com" style="sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;fillColor=#B0084D;strokeColor=none;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=left;html=1;fontSize=12;fontStyle=0;aspect=fixed;pointerEvents=1;shape=mxgraph.aws4.mq_broker;" parent="1" vertex="1">
+					<mxGeometry width="78" height="78" as="geometry" x="-160" y="-233" />
+				</mxCell>
+				<mxCell id="vertex:http:domain.com" value="&lt;b&gt;Name&lt;/b&gt;: on-prem-server&lt;BR&gt;&lt;b&gt;ID&lt;/b&gt;: domain.com" style="outlineConnect=0;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=left;html=1;shape=mxgraph.aws3.http_protocol;fillColor=#5294CF;gradientColor=none;" parent="1" vertex="1">
+					<mxGeometry width="63" height="66" as="geometry" x="103" y="-420" />
+				</mxCell>
+				<mxCell id="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:mq_broker:host.broker.com" style="endFill=0;endArrow=none;endArrow=none;" parent="1" source="vertex:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name" target="vertex:mq_broker:host.broker.com" edge="2">
+					<mxGeometry as="geometry" />
+				</mxCell>
+				<mxCell id="label:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:mq_broker:host.broker.com" value="Publish user activity log" style="edgeLabel;html=1;align=left;verticalAlign=middle;resizable=0;points=[];labelBackgroundColor=none;" parent="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:mq_broker:host.broker.com" vertex="1" connectable="0">
+					<mxGeometry relative="1" as="geometry">
+						<mxPoint as="offset" x="-49" y="-16" />
+					</mxGeometry>
+				</mxCell>
+				<mxCell id="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:http:domain.com" style="endFill=0;endArrow=none;endArrow=none;" parent="1" source="vertex:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name" target="vertex:http:domain.com" edge="2">
+					<mxGeometry as="geometry" />
+				</mxCell>
+				<mxCell id="label:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:http:domain.com" value="HTTP GET user actions" style="edgeLabel;html=1;align=left;verticalAlign=middle;resizable=0;points=[];labelBackgroundColor=none;" parent="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:http:domain.com" vertex="1" connectable="0">
+					<mxGeometry relative="1" as="geometry">
+						<mxPoint as="offset" y="22" />
+					</mxGeometry>
+				</mxCell>
+				<mxCell id="vertex:http:domain2.com" value="&lt;b&gt;Name&lt;/b&gt;: oauth-server&lt;BR&gt;&lt;b&gt;ID&lt;/b&gt;: domain2.com" style="outlineConnect=0;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=left;html=1;shape=mxgraph.aws3.http_protocol;fillColor=#5294CF;gradientColor=none;" parent="1" vertex="1">
+					<mxGeometry width="63" height="66" as="geometry" />
+				</mxCell>
+				<mxCell id="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:http:domain2.com" style="endFill=0;endArrow=none;endArrow=none;" parent="1" source="vertex:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name" target="vertex:http:domain2.com" edge="2">
+					<mxGeometry as="geometry" />
+				</mxCell>
+				<mxCell id="label:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:http:domain2.com" value="check user authority" style="edgeLabel;html=1;align=left;verticalAlign=middle;resizable=0;points=[];labelBackgroundColor=none;" parent="edge:lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name:to:http:domain2.com" vertex="1" connectable="0">
+					<mxGeometry relative="1" as="geometry">
+						<mxPoint as="offset" />
+					</mxGeometry>
+				</mxCell>
+			</root>
+		</mxGraphModel>
+	</diagram>
+</mxfile>

docs/docs/core-components/yaml.md

@@ -15,20 +15,29 @@ New (v0.3.8)
 {: .highlight }
 Ingest extra resources from yaml configuration into DRAWIO diagram. Allows to add vertices and edges to empty diagram
 or to existing one. To cover the case if there are relationships that you can not programmatically query but want to visualtize.
-## Node Type: ``snapshot``
 
-## yaml file with declaration of resource:
+{: .note-title }
+> ``YAML``-format supports declaration using 3 forms dialects for vertices and edges and also any mix of them:
+>- src/dst are linked to yaml vertices by name
+>- src/dst are linked by ARN (ARN can be present in same yaml, or loaded programmatically)
+>- mixed of 1st and 2nd
+
+
+## Option 1: All resources are from YAML:
+{: .d-inline-block }
 
-Currently, it is supports 3 different syntax's of declaration: 
-- src/dst are linked to yaml vertices by name
-- src/dst are linked by ARN (ARN can be present in same yaml, or loaded programmatically)
-- mixed of 1st and 2nd
+All of these dialects are present in the first ``yaml`` snippet:
+
+## yaml file with declaration of resource:
 
 ```yaml
 {% root_include ../samples/samples/augmented_resources.yaml %}
 ```
 
 ## Code Snippet:
+{: .highlight }
+``read_coords_from_file`` is used for positioning Vertices - coordinates from previous version ``drawio`` file will be reused for
+Vertices that have same ``ID``. This function does not reload Vertices from previous version, it only operates with coordinates history.
 
 ```python
 {% root_include_snippet ../tests/core/test_yaml.py yaml%}
@@ -45,7 +54,7 @@ Download generated ``yaml.drawio``:
 
 [Download](output/drawio/yaml.drawio){: .btn .btn-purple }
 
-## Augment resources both from code and YAML:
+## Option 2: resources are in the code (Diagrams as a Code), additionally augmented from YAML:
 
 {: .highlight }
 Other option is to combine Diagrams as Code (DaC) by declaring all resources in code and also ingest additional vertices from YAML file.
@@ -60,7 +69,7 @@ This is very useful when you have custom resources that are not supported by lib
 ## Code Snippet:
 
 ```python
-{% root_include_snippet ../tests/core/test_yaml.py yaml_to_existing_file %}
+{% root_include_snippet ../tests/core/test_yaml.py yaml_with_code %}
 ```
 
 ## Rendering:
@@ -73,3 +82,34 @@ This is very useful when you have custom resources that are not supported by lib
 Download generated ``yaml2.drawio``:
 
 [Download](output/drawio/yaml2.drawio){: .btn .btn-purple }
+
+
+## Option 3: Existing diagram has all resources, additionally augmented from YAML:
+
+{: .highlight }
+We already have ``drawio`` file with rendered resources (from previous example).
+Now we want to instrument ``multicloud-diagrams`` that there are additional resources that are declared in ``yaml`` that should be added.
+Previous resources will stay in ``drawio`` diagram, ``yaml``-based resources will be added to existing one.
+
+## yaml file with resources declaration:
+
+```yaml
+{% root_include ../samples/samples/augmented_resources3.yaml %}
+```
+
+## Code Snippet:
+
+```python
+{% root_include_snippet ../tests/core/test_yaml.py yaml_to_existing %}
+```
+
+## Rendering:
+
+![lambda](output/jpg/yaml3.jpg)
+
+
+### drawio file:
+
+Download generated ``yaml3.drawio``:
+
+[Download](output/drawio/yaml3.drawio){: .btn .btn-purple }

multicloud_diagrams/__init__.py

@@ -423,7 +423,7 @@ def read_nodes_from_file(self, file_name: str):
             # Layers
             mx_cells = tree.findall("./*/*/*/")
             for layer in mx_cells:
-                if ('parent' in layer.attrib) and (int(layer.attrib['parent']) == 0):
+                if ('parent' in layer.attrib) and layer.attrib['parent'].isdigit() and (int(layer.attrib['parent']) == 0):
                     layer_id = int(layer.attrib['id'])
                     if layer_id > 1:
                         self.layers[layer_id] = layer.attrib['value']

samples/samples/augmented_resources3.yaml

@@ -0,0 +1,11 @@
+vertices:
+  - name: oauth-server
+    type: http
+    id: domain2.com
+edges:
+  - {
+    src_id: arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name,
+    src_type: lambda_function,
+    dst: oauth-server,
+    label: check user authority,
+    link_type: none }

tests/core/test_yaml.py

@@ -32,7 +32,7 @@ def test_yaml(self):
         # docs
         self.mcd = mcd
 
-    def test_yaml_to_existing_file(self):
+    def test_yaml_with_code(self):
         # docs
         self.node_type = 'yaml2'
 
@@ -42,9 +42,11 @@ def test_yaml_to_existing_file(self):
         mcd.read_coords_from_file(output_file)
 
         # Diagrams as a Code: add Lambda and DynamoDB
-        mcd.add_vertex(node_id="arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name", node_name='prod-lambda-name',
+        mcd.add_vertex(node_id="arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name",
+                       node_name='prod-lambda-name',
                        node_type='lambda_function')
-        mcd.add_vertex(node_id='arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table', node_name='prod-dynamo-table',
+        mcd.add_vertex(node_id='arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table',
+                       node_name='prod-dynamo-table',
                        node_type='dynamo')
         mcd.add_link('lambda_function:arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name',
                      'dynamo:arn:aws:dynamodb:eu-west-1:123456789012:table/prod-dynamo-table',
@@ -68,3 +70,32 @@ def test_yaml_to_existing_file(self):
 
         # docs
         self.mcd = mcd
+
+    def test_yaml_to_existing(self):
+        # docs
+        self.node_type = 'yaml3'
+
+        # given
+        mcd = MultiCloudDiagrams()
+        input_file_previous_version = 'docs/docs/core-components/output/drawio/yaml2.drawio'
+        # all nodes are loaded and operable, now we can build augmented relations from external sources
+        mcd.read_nodes_from_file(input_file_previous_version)
+
+        # when
+        # Add additional resources from YAML-file
+        mcd.augment_from_yaml('samples/samples/augmented_resources3.yaml')
+
+        # then
+        # expected = {
+        #     'id': 'vertex:Integration Response:list',
+        #     'parent': '1',
+        #     'style': 'swimlane;fontStyle=0;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;'
+        #              'resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;',
+        #     'value': '<b>Integration Response</b>',
+        #     'vertex': '1'
+        # }
+
+        # self.verify_list(expected=expected, mx_file=mcd.mx_file, resource_name='LSI:users_to_model-users-idx', expected_list=expected_list)
+
+        # docs
+        self.mcd = mcd