auto generate examples.md

.gitignore

@@ -5,3 +5,5 @@ tests/lcov
 out
 custom
 .pytest_cache
+docs/example
+examples.md

tests/common_fixtures.py

@@ -158,6 +158,15 @@ def zynqmp() -> Dict:
 
 #     return data
 
+markdown = pathlib.Path("examples.md")
+
+@pytest.fixture(scope="session", autouse=True)
+def markdown_setup():
+    # prepare something ahead of all tests
+    markdown.unlink(missing_ok=True)
+    with open(markdown, 'a', encoding='utf-8') as fp:
+        fp.write("|description|diagram|\n")
+        fp.write("|-|-|\n")   
 
 @pytest.fixture
 def file_setup(request):
@@ -171,6 +180,22 @@ def file_setup(request):
     table_image = pathlib.Path(f"{request.param['file_path']}_table.png")
     table_image.unlink(missing_ok=True)
 
-    return {"report": report, "diagram_image": diagram_image, "table_image": table_image}
+    yield {"report": report, "diagram_image": diagram_image, "table_image": table_image}
+
+    if "docs/example" in request.param['file_path']:
+        with open(markdown, 'a', encoding='utf-8') as mdfp:
+
+            markdown_comment = str(request.param['markdown_comment']).replace("\n","")
+            markdown_comment = markdown_comment.replace("-","<br>-")
+
+            mdfp.write( f"|{markdown_comment if 'markdown_comment' in request.param else 'No Description?'}|![]( {request.param['file_path']}_diagram.png )|\n")    
+            mdfp.write( f"||![]( {request.param['file_path']}_table.png )|\n")    
+            mdfp.write( f"||[{request.param['file_path']}.json]({request.param['file_path']}.json)<pre>" )
+
+            with open(f"{request.param['file_path']}.json", "r", encoding="utf-8") as jsonfp:
+                mdfp.write( jsonfp.read().replace("\n", "<BR>") )
+
+            mdfp.write( f"</pre>|\n" )
 
+    print("FINISHED")
 

tests/test_docs.py

@@ -4,14 +4,18 @@
 import pathlib
 import pytest
 import PIL.Image
-from tests.common_fixtures import input, file_setup, zynqmp
+from tests.common_fixtures import input, file_setup, markdown_setup
 import json
 
-
-
-
-@pytest.mark.parametrize("file_setup", [{"file_path": "docs/example/example_end_collision"}], indirect=True)
-def test_generate_doc_example_end_collision(file_setup):
+@pytest.mark.parametrize(
+        "file_setup", 
+        [
+            {
+                "file_path": "docs/example/example_end_collisions",
+                "markdown_comment": "Region collision with diagram max address"
+            }
+        ], indirect=True)
+def test_generate_doc_example_end_collisions(file_setup):
     """ """
 
 
@@ -30,6 +34,10 @@ def test_generate_doc_example_end_collision(file_setup):
 
         d = mm.diagram.Diagram()
 
+        output_file = pathlib.Path("docs/example/example_end_collisions.json")
+        with output_file.open("w") as fp:
+            fp.write(d.model.model_dump_json(indent=2))    
+
         # we only have a single mmd in mmd_list for this test
         for region_image in d.mmd_list[0].image_list:
             if region_image.name == "kernel":
@@ -54,10 +62,18 @@ def test_generate_doc_example_end_collision(file_setup):
         # reduced void threshold, so empty section between rootfs and dtb should be voided, making the file smaller
         assert file_setup["table_image"].exists()
 
-@pytest.mark.parametrize("file_setup", [{"file_path": "docs/example/example_region_collisions"}], indirect=True)
+@pytest.mark.parametrize(
+        "file_setup", 
+        [
+            {
+                "file_path": "docs/example/example_region_collisions",
+                "markdown_comment": "Region collisions with other regions"
+            }
+        ], indirect=True)
 def test_generate_doc_example_region_collisions(file_setup):
     """ """
-
+
+
     with unittest.mock.patch(
         "sys.argv",
         [
@@ -73,6 +89,10 @@ def test_generate_doc_example_region_collisions(file_setup):
 
         d =mm.diagram.Diagram()
 
+        output_file = pathlib.Path("docs/example/example_region_collisions.json")
+        with output_file.open("w") as fp:
+            fp.write(d.model.model_dump_json(indent=2))    
+
         # we only have a single mmd in mmd_list for this test
         for region_image in d.mmd_list[0].image_list:
             if region_image.name == "kernel":
@@ -95,7 +115,14 @@ def test_generate_doc_example_region_collisions(file_setup):
 
         assert file_setup["table_image"].exists()
 
-@pytest.mark.parametrize("file_setup", [{"file_path": "docs/example/example_two_maps"}], indirect=True)
+@pytest.mark.parametrize(
+        "file_setup", 
+        [
+            {
+                "file_path": "docs/example/example_two_maps",
+                "markdown_comment": "Diagram with two memory maps"
+            }
+        ], indirect=True)
 def test_generate_doc_example_two_maps(input, file_setup):
     """ """
 
@@ -111,7 +138,7 @@ def test_generate_doc_example_two_maps(input, file_setup):
         "size": "0x10"
     }
 
-    input_file = pathlib.Path("./docs/example/two_maps_input.json")
+    input_file = pathlib.Path("./docs/example/example_two_maps.json")
     with input_file.open("w") as fp:
         fp.write(json.dumps(input, indent=2))
 
@@ -140,7 +167,14 @@ def test_generate_doc_example_two_maps(input, file_setup):
 
         assert file_setup["table_image"].exists()
 
-@pytest.mark.parametrize("file_setup", [{"file_path": "docs/example/example_three_maps"}], indirect=True)
+@pytest.mark.parametrize(
+        "file_setup", 
+        [
+            {
+                "file_path": "docs/example/example_three_maps",
+                "markdown_comment": "Diagram with three memory maps"
+            }
+        ], indirect=True)
 def test_generate_doc_example_three_maps(input, file_setup):
 
     """ """
@@ -190,7 +224,7 @@ def test_generate_doc_example_three_maps(input, file_setup):
         }        
     }
 
-    input_file = pathlib.Path("./docs/example/three_maps_input.json")
+    input_file = pathlib.Path("./docs/example/example_three_maps.json")
     with input_file.open("w") as fp:
         fp.write(json.dumps(input, indent=2))