Merge pull request #3837 from hathach/hil-setup-writeupHEADmaster

docs: add hardware-in-the-loop rig reference

2 files changed, 53 insertions, 0 deletions

diff --git a/tools/gen_doc.py b/tools/gen_doc.py
index 3920531d5..41a60c0b6 100755
--- a/tools/gen_doc.py
+++ b/tools/gen_doc.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import json
 import re
 import pandas as pd
 from tabulate import tabulate
@@ -110,8 +111,59 @@ Following boards are supported"""
 
 
 # -----------------------------------------
+# HIL rig rosters
+# -----------------------------------------
+def hil_cell(text):
+    """A '|' in free-form roster text would silently split the markdown row."""
+    return ' '.join((text or '').split()).replace('|', '\\|')
+
+
+def hil_rows(boards):
+    rows = []
+    for b in boards:
+        tests = b.get('tests', {})
+        if 'only' in tests:
+            roles = sorted({t.split('/')[0] for t in tests['only']})
+        else:
+            roles = [r for r in ('device', 'host', 'dual') if tests.get(r)]
+        rows.append([
+            b['name'],
+            ', '.join(roles),
+            b.get('flasher', {}).get('name', ''),
+            hil_cell(', '.join(v['name'] for v in b.get('variant') or [])),
+            hil_cell(b.get('comment') or tests.get('comment')),
+        ])
+    return rows
+
+
+def gen_hil_boards_doc():
+    tinyusb = json.loads((Path(TOP) / "test/hil/tinyusb.json").read_text())
+    hfp = json.loads((Path(TOP) / "test/hil/hfp.json").read_text())
+    sections = [
+        ("ci rig", "test/hil/tinyusb.json", tinyusb.get('boards', [])),
+        ("hfp rig", "test/hil/hfp.json", hfp.get('boards', [])),
+    ]
+    headers = ['Board', 'Roles', 'Flasher', 'Variants', 'Note']
+
+    out = ["<!-- Generated by tools/gen_doc.py - do not edit. -->", ""]
+    for title, src, boards in sections:
+        if not boards:
+            continue
+        out.append(f"### {title}")
+        out.append("")
+        out.append(f"{len(boards)} boards, from `{src}`.")
+        out.append("")
+        out.append(tabulate(hil_rows(boards), headers=headers, tablefmt='github'))
+        out.append("")
+
+    hil_md = Path(TOP) / "docs/reference/hil_boards.md"
+    hil_md.write_text('\n'.join(out))
+
+
+# -----------------------------------------
 # Main
 # -----------------------------------------
 if __name__ == "__main__":
     gen_deps_doc()
     gen_boards_doc()
+    gen_hil_boards_doc()
diff --git a/tools/make_release.py b/tools/make_release.py
index 65226834f..ec4755f34 100755
--- a/tools/make_release.py
+++ b/tools/make_release.py
@@ -59,6 +59,7 @@ with open(f_sonar_properties, 'w') as f:
 # gen docs
 gen_doc.gen_deps_doc()
 gen_doc.gen_boards_doc()
+gen_doc.gen_hil_boards_doc()
 
 # gen presets
 gen_presets.main()