embed metadata to family.c and board.h to generate supported boards doc

tools/gen_doc.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import re
 import pandas as pd
 from tabulate import tabulate
 from pathlib import Path
@@ -11,7 +12,6 @@ TOP = Path(__file__).parent.parent.resolve()
 # -----------------------------------------
 # Dependencies
 # -----------------------------------------
-
 def gen_deps_doc():
     deps_rst = Path(TOP) / "docs/reference/dependencies.rst"
     df = pd.DataFrame.from_dict(deps_all, orient='index', columns=['Repo', 'Commit', 'Required by'])
@@ -32,5 +32,81 @@ MCU low-level peripheral driver and external libraries for building TinyUSB exam
         f.write(outstr)
 
 
+# -----------------------------------------
+# Dependencies
+# -----------------------------------------
+def extract_metadata(file_path):
+    metadata = {}
+    try:
+        with open(file_path, 'r') as file:
+            content = file.read()
+            # Match metadata block
+            match = re.search(r'/\*\s*metadata:(.*?)\*/', content, re.DOTALL)
+            if match:
+                block = match.group(1)
+                # Extract key-value pairs
+                for line in block.splitlines():
+                    key_value = re.match(r'\s*(\w+):\s*(.+)', line)
+                    if key_value:
+                        key, value = key_value.groups()
+                        metadata[key] = value.strip()
+    except FileNotFoundError:
+        pass
+    return metadata
+
+
+def gen_boards_doc():
+    # 'Manufacturer' : { 'Board' }
+    vendor_data = {}
+    # 'Board' : [ 'Name', 'Family', 'url', 'note' ]
+    all_boards = {}
+    #  extract metadata from family.c
+    for family_dir in sorted((Path(TOP) / "hw/bsp").iterdir()):
+        if family_dir.is_dir():
+            family_c = family_dir / "family.c"
+            if not family_c.exists():
+                family_c = family_dir / "boards/family.c"
+            f_meta = extract_metadata(family_c)
+            if not f_meta:
+                continue
+            manuf = f_meta.get('manufacturer', '')
+            if manuf not in vendor_data:
+                vendor_data[manuf] = {}
+            # extract metadata from board.h
+            for board_dir in sorted((family_dir / "boards").iterdir()):
+                if board_dir.is_dir():
+                    b_meta = extract_metadata(board_dir / "board.h")
+                    if not b_meta:
+                        continue
+                    b_entry = [
+                        b_meta.get('name', ''),
+                        family_dir.name,
+                        b_meta.get('url', ''),
+                        b_meta.get('note', '')
+                    ]
+                    vendor_data[manuf][board_dir.name] = b_entry
+    boards_rst = Path(TOP) / "docs/reference/boards.rst"
+    with boards_rst.open('w') as f:
+        title = f"""\
+****************
+Supported Boards
+****************
+
+Following boards are supported and can be used to run stock examples
+
+"""
+        f.write(title)
+        for manuf, boards in sorted(vendor_data.items()):
+            f.write(f"\n\n{manuf}\n")
+            f.write(f"{'=' * len(manuf)}\n\n")
+            df = pd.DataFrame.from_dict(boards, orient='index', columns=['Name', 'Family', 'URL', 'Note'])
+            df = df.rename_axis("Board")
+            f.write(tabulate(df, headers="keys", tablefmt='rst'))
+
+
+# -----------------------------------------
+# Main
+# -----------------------------------------
 if __name__ == "__main__":
     gen_deps_doc()
+    gen_boards_doc()