From f26a520bb20ef718f703a62037acf07f08b63d8d Mon Sep 17 00:00:00 2001
From: Shareef Jalloq <shareef@jalloq.co.uk>
Date: Mon, 16 Mar 2026 15:56:56 +0000
Subject: [PATCH] feat: add enum to docnode

This commit adds enum support.  The field summary table gets an enum
column if any field has an enumerate type and each field description
gains a table defining those types.
---
 src/sphinx_peakrdl/directives/docnode.py | 40 +++++++++++++++++++++---
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/src/sphinx_peakrdl/directives/docnode.py b/src/sphinx_peakrdl/directives/docnode.py
index 3f39142..61a981b 100644
--- a/src/sphinx_peakrdl/directives/docnode.py
+++ b/src/sphinx_peakrdl/directives/docnode.py
@@ -9,6 +9,7 @@
 from docutils.parsers.rst import directives
 
 from systemrdl.node import Node, RegNode, AddressableNode, SignalNode, RootNode
+from systemrdl.rdltypes import UserEnum
 from systemrdl.rdltypes.references import PropertyReference
 from systemrdl.source_ref import FileSourceRef, DetailedFileSourceRef
 
@@ -209,6 +210,17 @@ def make_rdl_node_doc(self, rdl_node: Node) -> Sequence[nodes.Element]:
         return doc_nodes
 
 
+    def _build_enum_table(self, enum_cls: type) -> nodes.table:
+        """Build a table of enum members showing value, name, and description."""
+        table = Table(["Value", "Name", "Description"])
+        for member in enum_cls:
+            table.add_row([
+                f"{member.value:#x}",
+                member.name,
+                member.rdl_desc or "-",
+            ])
+        return table.as_node()
+
     def make_rdl_reg_doc(self, rdl_node: RegNode) -> Sequence[nodes.Element]:
         # Info Field List Header
         fl = self.get_info_header(rdl_node)
@@ -216,8 +228,16 @@ def make_rdl_reg_doc(self, rdl_node: RegNode) -> Sequence[nodes.Element]:
         # Description
         desc_paragraph = self.get_rdl_desc(rdl_node)
 
+        # Check if any field uses an enum encoding
+        has_enums = any(
+            field.get_property("encode") for field in rdl_node.fields()
+        )
+
         # Field Table
-        table = Table(["Bits", "Identifier", "Access", "Reset", "Name"])
+        headings = ["Bits", "Identifier", "Access", "Reset", "Name"]
+        if has_enums:
+            headings.append("Encode")
+        table = Table(headings)
         for field in reversed(rdl_node.fields()):
             # Is actual field
             if field.width == 1:
@@ -245,13 +265,19 @@ def make_rdl_reg_doc(self, rdl_node: RegNode) -> Sequence[nodes.Element]:
             else:
                 reset = self.get_rdl_xref(reset_value)
 
-            table.add_row([
+            row = [
                 bitrange,
                 field.inst_name,
                 access,
                 reset,
                 field.get_property("name", default="-"),
-            ])
+            ]
+            if has_enums:
+                encode = field.get_property("encode")
+                encode_name = encode.type_name if encode and issubclass(encode, UserEnum) else "-"
+                row.append(encode_name)
+
+            table.add_row(row)
 
         # Field descriptions
         def_list = nodes.definition_list()
@@ -259,14 +285,18 @@ def make_rdl_reg_doc(self, rdl_node: RegNode) -> Sequence[nodes.Element]:
             desc = field.get_property("desc")
             if not desc:
                 continue
+            encode = field.get_property("encode")
 
             dli = nodes.definition_list_item()
             def_list.append(dli)
 
             dl_term = nodes.term(text = field.inst_name)
             dl_def = nodes.definition()
-            dl_def_p = self.get_rdl_desc(field)
-            dl_def.append(dl_def_p)
+            if desc:
+                dl_def_p = self.get_rdl_desc(field)
+                dl_def.append(dl_def_p)
+            if encode and issubclass(encode, UserEnum):
+                dl_def.append(self._build_enum_table(encode))
 
             dli.append(dl_term)
             dli.append(dl_def)