updated doc generation

doc/example/main.md

@@ -0,0 +1,4 @@
+|description|options|full|with void regions|
+|:-:|:-:|:-:|:-:|
+|No overlapping memory regions|<b>max height:</b> 1000 (0x3e8) bytes,<br><b>void threshold:</b> 200 (0xC8) bytes|![](tests.test_docs_normal_full.png)|![](tests.test_docs_normal_cropped.png)|
+|Overlapping memory regions|<b>max height:</b> 1000 (0x3e8) bytes,<br><b>void threshold:</b> 200 (0xC8) bytes|![](tests.test_docs_collisions_full.png)|![](tests.test_docs_collisions_cropped.png)|

doc/example/tests.test_docs_collisions.md

@@ -0,0 +1,6 @@
+![memory map diagram](tests.test_docs_collisions.png)
+|name|origin|size|remaining|collisions
+|:-|:-|:-|:-|:-|
+|<span style='color:darkslateblue'>kernel</span>|0x10|0x60|-0x20|{'rootfs': '0x50'}|
+|<span style='color:gray'>rootfs</span>|0x50|0x50|-0x10|{'kernel': '0x50', 'dtb': '0x90'}|
+|<span style='color:limegreen'>dtb</span>|0x90|0x30|0x328|{'rootfs': '0x90'}|

doc/example/tests.test_docs_normal.md

@@ -0,0 +1,6 @@
+![memory map diagram](tests.test_docs_normal.png)
+|name|origin|size|remaining|collisions
+|:-|:-|:-|:-|:-|
+|<span style='color:olivedrab'>kernel</span>|0x10|0x30|0x10|{}|
+|<span style='color:darkblue'>rootfs</span>|0x50|0x30|0x110|{}|
+|<span style='color:purple'>dtb</span>|0x190|0x30|0x228|{}|

readme.md

@@ -3,13 +3,13 @@
 
 Tool for mapping of regions in memory, specifcally for visualising and troubleshooting region overlap/collision.
 
-![](doc/example/report.png)
+![](doc/example/tests.test_docs_normal_cropped.png)
 
 As well as the `png` format diagram image, a `markdown` report is also created:
 - inline image of the diagram
 - collision data table
 
-An example can be found in [doc/example/report.md](doc/example/report.md)
+An example can be found in [doc/example/main.md](doc/example/main.md)
 
 ### Usage:
 

tests/test_docs.py

@@ -1,48 +1,112 @@
 import unittest
 import mm.diagram
+import pathlib
+import pytest
+import PIL.Image
 
+@pytest.fixture
+def setup(request):
 
-def test_generate_doc_example():
+    report = pathlib.Path(f"doc/example/{__name__}{request.param['file_prefix']}.md")
+    report.unlink(missing_ok=True)
+
+    image_full = pathlib.Path(f"doc/example/{__name__}{request.param['file_prefix']}_full.png")
+    image_full.unlink(missing_ok=True)
+
+    image_cropped = pathlib.Path(f"doc/example/{__name__}{request.param['file_prefix']}_cropped.png")
+    image_cropped.unlink(missing_ok=True)
+
+    return {"report": report, "image_full": image_full, "image_cropped": image_cropped}
+
+@pytest.mark.parametrize('setup', [{'file_prefix': '_normal'}], indirect=True)
+def test_generate_doc_example_normal(setup):
     """  """
+
+    diagram_height = 1000
     with unittest.mock.patch('sys.argv',
                              ['mmap_digram.diagram',
                               'kernel',
                               '0x10',
-                              '0x50',
+                              '0x30',
                               'rootfs',
                               '0x50',
                               '0x30',
                               'dtb',
-                              '0x90',
-                              '0x30',
-                              'uboot',
-                              '0xD0',
-                              '0x50',
-                              'uboot-scr',
-                              '0x110',
+                              '0x190',
                               '0x30',
-                              "-o", "doc/example/report.md",
-                              "-s", "2"],
-                             ):
+                              "-o", str(setup['report']),
+                              "-l", hex(diagram_height),
+                              "-v", hex(200)
+                              ]):
+
         d = mm.diagram.MemoryMap()
+
+        # assumes the defaults haven't changed
+        assert d.args.scale == 1
+
         for region in d._region_list:
             if region.name == "kernel":
                 assert region._origin == "0x10"
-                assert region._size == "0x50"
-                assert region.remain == "-0x10"
+                assert region._size == "0x30"
+                assert region.remain == "0x10"
             if region.name == "rootfs":
                 assert region._origin == "0x50"
                 assert region._size == "0x30"
-                assert region.remain == "0x10"
+                assert region.remain == "0x110"
             if region.name == "dtb":
-                assert region._origin == "0x90"
+                assert region._origin == "0x190"
                 assert region._size == "0x30"
-                assert region.remain == "0x10"
-            if region.name == "uboot":
-                assert region._origin == "0xD0"
+                assert region.remain == "0x228"
+
+        assert setup['report'].exists()
+
+        assert setup['image_full'].exists()
+        found_size = PIL.Image.open(str(setup['image_full'])).size
+        assert found_size == (400, diagram_height)
+
+        # reduced void threshold, so empty section between rootfs and dtb should be voided, making the file smaller
+        assert setup['image_cropped'].exists()
+        found_size = PIL.Image.open(str(setup['image_cropped'])).size
+        assert found_size == (400, 316)
+
+
+@pytest.mark.parametrize('setup', [{'file_prefix': '_collisions'}], indirect=True)
+def test_generate_doc_example_collisions(setup):
+    """  """
+    diagram_height = hex(1000)
+    with unittest.mock.patch('sys.argv',
+                             ['mmap_digram.diagram',
+                              'kernel',
+                              '0x10',
+                              '0x60',
+                              'rootfs',
+                              '0x50',
+                              '0x50',
+                              'dtb',
+                              '0x90',
+                              '0x30',
+                              "-o", str(setup['report']),
+                              "-l", diagram_height,
+                              "-v", hex(200)
+                              ]):
+
+        d = mm.diagram.MemoryMap()
+
+        for region in d._region_list:
+            if region.name == "kernel":
+                assert region._origin == "0x10"
+                assert region._size == "0x60"
+                assert region.remain == "-0x20"
+            if region.name == "rootfs":
+                assert region._origin == "0x50"
                 assert region._size == "0x50"
                 assert region.remain == "-0x10"
-            if region.name == "uboot-scr":
-                assert region._origin == "0x110"
+            if region.name == "dtb":
+                assert region._origin == "0x90"
                 assert region._size == "0x30"
-                assert region.remain == "0x690"
+                assert region.remain == "0x328"
+
+        assert setup['report'].exists()
+
+        assert setup['image_full'].exists()
+        assert setup['image_cropped'].exists()