Enhance api export

Author: robtaylor

pyproject.toml

@@ -63,4 +63,5 @@ dev = [
     "ruff>=0.9.2",
     "pytest>=7.2.0",
     "pytest-cov>=0.6",
+    "docstring-parser>=0.16",
 ]

tools/export_ips.py

@@ -4,26 +4,35 @@
 import sys
 
 from amaranth.lib import wiring
+from docstring_parser import parse_from_object
 
 import chipflow_digital_ip
 
 def children(mod):
-    stack = [(attr, getattr(mod, attr)) for attr in dir(mod) if not attr.startswith("_")]
+    level = "chipflow_digital_ip"
+    stack = [(f"{level}.{attr}", getattr(mod, attr)) for attr in dir(mod) if not attr.startswith("_")]
     done = []
     while stack:
         i = stack.pop()
         e,o = i
         if inspect.isclass(o) and o.__module__.startswith('chipflow_digital_ip') and issubclass(o, wiring.Component):
-            yield o
+            yield e,o
         if inspect.ismodule(o):
             if e in done:
                 continue
             done.append(e)
-            stack.extend([(attr, getattr(o, attr)) for attr in dir(o) if not attr.startswith("_")])
+            stack.extend([(f"{e}.{attr}", getattr(o, attr)) for attr in dir(o) if not attr.startswith("_")])
 
 gen = children(chipflow_digital_ip)
 output={}
-for cls in gen:
-    output[f"{cls.__module__}.{cls.__qualname__}"]=cls.__doc__
+for name, cls in gen:
+    docstring = parse_from_object(cls)
+    d = {
+        'short_description': docstring.short_description,
+        'long_description': docstring.long_description,
+        'params': [p.__dict__ for p in docstring.params],
+        'examples': [ e.__dict__ for e in docstring.examples],
+        }
+    output[name] = d
 
 json.dump(output, sys.stdout, indent=2)