Merge pull request #9278 from timchinowsky/main

Add board details and reporting to documentation utilities

Author: tannewt

docs/shared_bindings_matrix.py

@@ -26,8 +26,7 @@
 import pathlib
 import re
 import subprocess
-import sys
-import functools
+
 
 from concurrent.futures import ThreadPoolExecutor
 
@@ -57,7 +56,8 @@
 
 ALIASES_BRAND_NAMES = {
     "circuitplayground_express_4h": "Adafruit Circuit Playground Express 4-H",
-    "circuitplayground_express_digikey_pycon2019": "Circuit Playground Express Digi-Key PyCon 2019",
+    "circuitplayground_express_digikey_pycon2019":
+        "Circuit Playground Express Digi-Key PyCon 2019",
     "edgebadge": "Adafruit EdgeBadge",
     "pyportal_pynt": "Adafruit PyPortal Pynt",
     "gemma_m0_pycon2018": "Adafruit Gemma M0 PyCon 2018",
@@ -87,7 +87,7 @@
     "usb": "CIRCUITPY_PYUSB",
 }
 
-MODULES_NOT_IN_BINDINGS = [ "binascii", "errno", "json", "re", "ulab" ]
+MODULES_NOT_IN_BINDINGS = ["binascii", "errno", "json", "re", "ulab"]
 
 FROZEN_EXCLUDES = ["examples", "docs", "tests", "utils", "conf.py", "setup.py"]
 """Files and dirs at the root of a frozen directory that should be ignored.
@@ -105,7 +105,8 @@ def get_circuitpython_root_dir():
 
 
 def get_bindings():
-    """Get a list of modules in shared-bindings and ports/*/bindings based on folder names."""
+    """Get a list of modules in shared-bindings and ports/*/bindings
+    based on folder names."""
     shared_bindings_modules = [
         module.name
         for module in (get_circuitpython_root_dir() / "shared-bindings").iterdir()
@@ -114,7 +115,8 @@ def get_bindings():
     bindings_modules = []
     for d in get_circuitpython_root_dir().glob("ports/*/bindings"):
         bindings_modules.extend(module.name for module in d.iterdir() if d.is_dir())
-    return shared_bindings_modules + bindings_modules + MODULES_NOT_IN_BINDINGS + list(ADDITIONAL_MODULES.keys())
+    return shared_bindings_modules + bindings_modules + MODULES_NOT_IN_BINDINGS + \
+        list(ADDITIONAL_MODULES.keys())
 
 
 def get_board_mapping():
@@ -127,7 +129,6 @@ def get_board_mapping():
         board_path = root_dir / "ports" / port / "boards"
         for board_path in os.scandir(board_path):
             if board_path.is_dir():
-                board_files = os.listdir(board_path.path)
                 board_id = board_path.name
                 aliases = ALIASES_BY_BOARD.get(board_path.name, [])
                 boards[board_id] = {
@@ -181,7 +182,10 @@ def get_settings_from_makefile(port_dir, board_name):
                 }
 
     contents = subprocess.run(
-        ["make", "-C", port_dir, "-f", "Makefile", f"BOARD={board_name}", "print-CFLAGS", "print-CIRCUITPY_BUILD_EXTENSIONS", "print-FROZEN_MPY_DIRS", "print-SRC_PATTERNS", "print-SRC_SUPERVISOR"],
+        ["make", "-C", port_dir, "-f", "Makefile", f"BOARD={board_name}",
+         "print-CFLAGS", "print-CIRCUITPY_BUILD_EXTENSIONS",
+         "print-FROZEN_MPY_DIRS", "print-SRC_PATTERNS",
+         "print-SRC_SUPERVISOR"],
         encoding="utf-8",
         errors="replace",
         stdout=subprocess.PIPE,
@@ -288,7 +292,6 @@ def lookup_setting(settings, key, default=""):
     return value
 
 
-@functools.cache
 def all_ports_all_boards(ports=SUPPORTED_PORTS):
     for port in ports:
         port_dir = get_circuitpython_root_dir() / "ports" / port
@@ -298,7 +301,9 @@ def all_ports_all_boards(ports=SUPPORTED_PORTS):
             yield (port, entry)
 
 
-def support_matrix_by_board(use_branded_name=True, withurl=True):
+def support_matrix_by_board(use_branded_name=True, withurl=True,
+                            add_port=False, add_chips=False,
+                            add_pins=False, add_branded_name=False):
     """Compiles a list of the available core modules available for each
     board.
     """
@@ -309,17 +314,64 @@ def support_matrix(arg):
         port_dir = get_circuitpython_root_dir() / "ports" / port
         settings = get_settings_from_makefile(str(port_dir), entry.name)
 
-        if use_branded_name:
+        if use_branded_name or add_branded_name:
             with open(entry / "mpconfigboard.h") as get_name:
                 board_contents = get_name.read()
             board_name_re = re.search(
                 r"(?<=MICROPY_HW_BOARD_NAME)\s+(.+)", board_contents
             )
             if board_name_re:
-                board_name = board_name_re.group(1).strip('"')
+                branded_name = board_name_re.group(1).strip('"')
+                if '"' in branded_name:  # sometimes the closing " is not at line end
+                    branded_name = branded_name[:branded_name.index('"')]
+                board_name = branded_name
+
+        if use_branded_name:
+            board_name = branded_name
         else:
             board_name = entry.name
 
+        if add_chips:
+            with open(entry / "mpconfigboard.h") as get_name:
+                board_contents = get_name.read()
+            mcu_re = re.search(
+                r'(?<=MICROPY_HW_MCU_NAME)\s+(.+)', board_contents
+            )
+            if mcu_re:
+                mcu = mcu_re.group(1).strip('"')
+                if '"' in mcu:  # in case the closing " is not at line end
+                    mcu = mcu[:mcu.index('"')]
+            else:
+                mcu = ""
+            with open(entry / "mpconfigboard.mk") as get_name:
+                board_contents = get_name.read()
+            flash_re = re.search(
+                r'(?<=EXTERNAL_FLASH_DEVICES)\s+=\s+(.+)', board_contents
+            )
+            if flash_re:
+                # deal with the variability in the way multiple flash chips
+                # are denoted.  We want them to end up as a quoted,
+                # comma separated string
+                flash = flash_re.group(1).replace('"','')
+                flash = f'"{flash}"'
+            else:
+                flash = ""
+
+        if add_pins:
+            pins = []
+            try:
+                with open(entry / "pins.c") as get_name:
+                    pin_lines = get_name.readlines()
+            except FileNotFoundError:  # silabs boards have no pins.c
+                pass
+            else:
+                for p in pin_lines:
+                    pin_re = re.search(r"QSTR_([^\)]+).+pin_([^\)]+)", p)
+                    if pin_re:
+                        board_pin = pin_re.group(1)
+                        chip_pin = pin_re.group(2)
+                        pins.append((board_pin, chip_pin))
+
         board_modules = []
         for module in base:
             key = base[module]["key"]
@@ -344,14 +396,25 @@ def support_matrix(arg):
                 frozen_modules.sort()
 
         # generate alias boards too
+
+        board_info = {
+                       "modules": board_modules,
+                       "frozen_libraries": frozen_modules,
+                       "extensions": board_extensions,
+                      }
+        if add_branded_name:
+            board_info["branded_name"] = branded_name
+        if add_port:
+            board_info["port"] = port
+        if add_chips:
+            board_info["mcu"] = mcu
+            board_info["flash"] = flash
+        if add_pins:
+            board_info["pins"] = pins
         board_matrix = [
             (
                 board_name,
-                {
-                    "modules": board_modules,
-                    "frozen_libraries": frozen_modules,
-                    "extensions": board_extensions,
-                },
+                board_info
             )
         ]
         if entry.name in ALIASES_BY_BOARD:
@@ -361,14 +424,24 @@ def support_matrix(arg):
                         alias = ALIASES_BRAND_NAMES[alias]
                     else:
                         alias = alias.replace("_", " ").title()
+                board_info = {
+                    "modules": board_modules,
+                    "frozen_libraries": frozen_modules,
+                    "extensions": board_extensions,
+                    }
+                if add_branded_name:
+                    board_info["branded_name"] = branded_name
+                if add_port:
+                    board_info["port"] = port
+                if add_chips:
+                    board_info["mcu"] = mcu
+                    board_info["flash"] = flash
+                if add_pins:
+                    board_info["pins"] = pins
                 board_matrix.append(
                     (
                         alias,
-                        {
-                            "modules": board_modules,
-                            "frozen_libraries": frozen_modules,
-                            "extensions": board_extensions,
-                        },
+                        board_info
                     )
                 )